Programmer avec SPIP 2.1
Mahieu Marcillaud
15 janvier 2012 2 0.1 Notes sur cette documentation
0.1.1 Licence et libertés
Fruit de longues heures d’écriture, cee documentation est une somme de connais- sances issue de la communauté SPIP. Tout ce travail est distribué sous licence libre Creative Commons - Paternité - Partage des Conditions Initiales à l’Iden- tique (cc-by-sa). Vous pouvez utiliser ces textes quel que soit l’usage (y compris commercial), les modifier et les redistribuer à condition de laisser à vos lecteurs la même liberté de partage.
0.1.2 Une amélioration constante
Cee œuvre - en cours d’écriture - fait l’objet de nombreuses relectures mais n’est certainement pas indemne de toute erreur. N’hésitez pas à proposer des amélio- rations ou signaler des coquilles en utilisant le formulaire de suggestion mis à dis- position sur le site internet de la documentation (hp ://programmer.spip.org). Vous pouvez aussi discuter de l’organisation (des contenus, de la technique) et des traductions sur la liste de discussion « spip-programmer » (sur abonnement).
0.1.3 Écrire un apitre
Si vous êtes motivé par ce projet, vous pouvez proposer d’écrire un chapitre sur un sujet que vous maitrisez ou refondre un chapitre existant pour le clarifier ou le compléter. Nous essaierons alors de vous accompagner et vous soutenir dans cee tâche.
0.1.4 Traductions
Vous pouvez également participer à la traduction de cee documentation en an- glais et en espagnol. L’espace privé du site (hp ://programmer.spip.org) permet de discuter des traductions en cours d’élaboration. Ceci dit, il n’est pas prévu de traduire la documentation dans d’autres langues tant que l’organisation des différents chapitres n’est pas stabilisée, ce qui peut durer encore plusieurs mois. 0.1. NOTES SUR CETTE DOCUMENTATION 3
0.1.5 Codes informatiques et caractéristiques des langues
Par souci de compatibilité, les codes informatiques qui servent d’exemple ne contiennent que des caractères du code ASCII. Cela signifie entre autre que vous ne trouverez aucun accent dans les commentaires accompagnant les exemples dans l’ensemble de la documentation. Ne soyez donc pas étonnés par cee ab- sence. Bonne lecture. 4 Première partie
Introduction
5
0.2. QU’EST-CE QUE SPIP ? 7
Présentation de SPIP et de son fonctionnement général.
0.2 ’est-ce que SPIP ?
SPIP 2 est un logiciel libre développé sous licence GNU/GPL3. Historiquement utilisé comme un système de publication de contenu, il devient progressivement une plateforme de développement permeant de créer des interfaces mainte- nables et extensibles quelle que soit la structure des données gérées.
0.3 e peut-on faire avec SPIP ?
SPIP est particulièrement adapté pour des portails éditoriaux mais peut tout aus- si bien être utilisé comme système d’auto-publication (blog), de wiki, de réseau social ou pour gérer toute donnée issue de MySQL, PostGres ou SQLite. Des ex- tensions proposent aussi des interactions avec XML.
0.4 Comment fonctionne-t-il ?
SPIP 2.1 nécessite a minima PHP 5.x (et 10 Mo de mémoire pour PHP) ainsi qu’une base de données (MySQL, PostGres ou SQLite). Il possède une interface publique (front-office), visible de tous les visiteurs du site (ou en fonction d’autorisations particulières) et une interface privée (back-office) seulement accessible aux personnes autorisées et permeant d’administrer le lo- giciel et les contenus du site.
0.5 Des gabarits appelés « squelettes »
Toute l’interface publique (dans le répertoire squelees-dist) et une partie de l’interface privée (dans le répertoire prive) utilisent, pour s’afficher, des gabarits appelés « squelees », mélange de code à produire (le plus souvent HTML) et de syntaxe SPIP. Lorsqu’un visiteur demande à afficher la page d’accueil du site, SPIP va créer une 8
page HTML grâce à un squelee nommé sommaire.html. Chaque type de page possède un squelee particulier, tel que article.html, rubrique.html… Ces squelees sont analysés puis compilés en langage PHP. Ce résultat est mis en cache. Ce sont ces fichiers PHP qui servent à produire ensuite les pages HTML renvoyées aux visiteurs d’un site. Pages qui sont elles-aussi mises en cache.
0.6 Simple et rapide
Les boucles
1
2
- #TITRE
3
4
5
6
7
Dans cet exemple, la boucle identifiée _art fait une sélection dans la table SQL nommée ARTICLES. Elle trie les données par date anti-chronologique {!par date} et sélectionne les 5 premiers résultats {0,5}. La balise #URL_ARTICLE affiche un lien vers la page présentant l’article complet, alors que la balise #TITRE affiche le titre de l’article. Résultat :
1
- Récursivité
- Paramètre
- Argument
- Adapter tous ses squelettes en une seule opération
- Afficher un formulaire d’édition, si autorisé
2 ^^I
3 ^^I
4 ^^I
5 ^^I
6 ^^I
7
Écriture des squelettes
9
11
SPIP génère des pages HTML à partir de fichiers appelés squelettes contenant un mélange de code HTML, de boucles et de critères, de balises et de filtres. Sa force est de pouvoir extraire du contenu de base de données de manière simple et compréhensible. 12 13
Chapitre 1
Boucles
Une boucle permet de sélectionner du contenu issu d’une base de données. Concrètement, elle sera traduite par une requête SQL optimisée permeant d’ex- traire le contenu demandé.
1.1 Syntaxe des boucles
Une boucle déclare donc une table SQL, sur laquelle extraire les informations, ainsi que des critères de sélection.
1
2 ... pour chaque réponse...
3
Une boucle possède obligatoirement un nom (identifiant unique à l’intérieur d’un même squelee), ce nom est accolé au mot BOUCLE. Ici donc, le nom de la boucle est « _nom ». La table est définie soit par un alias (alors écrit en majuscules), soit par le nom réel de la table dans sa véritable casse, par exemple « spip_articles ».
Les critères sont écrits ensuite, entre accolades, par exemple {par nom} pour trier les résultats dans l’ordre alphabétique selon le champ « nom » de la table SQL en question. 14 CHAPITRE 1. BOUCLES
1.1.1 Exemple
Cee boucle liste toutes les images du site. Le critère {extension IN jpg,png,gif} permet de sélectionner les fichiers possé- dant une extension parmi les trois listées.
1
2 [(#FICHIER|image_reduire{300})]
3
La balise #FICHIER contient l’adresse du document, auquel on applique un filtre nommé « image_reduire » qui redimensionne l’image automatiquement à 300 pixels si sa taille est plus grande et retourne une balise HTML permeant d’afficher l’image (balise )
1.2 Syntaxe complète des boucles
Les boucles, comme d’ailleurs les balises, possèdent une syntaxe permeant de multiples compositions. Des parties optionnelles s’affichent une seule fois (et non pour chaque élément). Une partie alternative s’affiche uniquement si la boucle ne renvoie aucun contenu. Voici la syntaxe (x étant l’identifiant de la boucle) :
1
2 une seule fois avant
3
4 pour chaque élément
5
6 une seule fois après
7
8 afficher ceci s’il n’y a pas de résultat
9 1.2. SYNTAXE COMPLÈTE DES BOUCLES 15
1.2.1 Exemple
Cee boucle sélectionne les 5 derniers articles publiés sur le site. Ici, les balises HTML
et
1
2
- #TITRE, [(#DATE|affdate)]
3
4
5
6
7
La balise #DATE affiche la date de publication de l’article. On lui affecte un filtre « affdate » supplémentaire permeant d’écrire la date dans la langue du contenu. Résultat :
1
- Contenu d’un fichier exec (squelette), 13 octobre 2009
- Liens AJAX, 1er octobre 2009
- Forcer la langue selon le visiteur, 27 septembre 2009
- Definition, 27 September 2009
- List of current pipelines, 27 September 2009
2
3
4
5
6
7
Il est souvent utile d’imbriquer des boucles les unes dans les autres pour afficher ce que l’on souhaite. Ces imbrications permeent d’utiliser des valeurs issues d’une première boucle comme critère de sélection de la seconde.
1
2 ^^I#ID_TABLE
3 ^^I
4 ^^I^^I...
5 ^^I
6
1.3.1 Exemple
Ici, nous listons les articles contenus dans les premières rubriques du site grâce au critère {racine} qui sélectionne les rubriques de premier niveau (à la racine du site), que l’on appelle généralement « secteur » :
1
2
- #TITRE
5
6
- #TITRE
7
8
9
10
11
12
3
4
13
14
15 1.4. LES BOUCLES RÉCURSIVES 17
La boucle ARTICLES contient simplement un critère de tri {par titre} et un cri- tère {id_rubrique}. Ce dernier indique de sélectionner les articles appartenant à la même rubrique. Résultat :
1
- en
3 ^^I
- fr
5 ^^I^^I
- Notes sur cette documentation
- Autre article
6 ^^I^^I^^I
7 ^^I^^I^^I
8 ^^I^^I
9 ^^I
2 ^^I
4 ^^I
10
1.4 Les boucles récursives
Une boucle dite récursive (n), contenue dans une boucle parente (x), permet d’exécuter la boucle (x) une nouvelle fois, en transmeant automatiquement les paramètres nécessaires. Donc, à l’intérieur de la boucle (x), on appelle cee même boucle (c’est ce qu’on nomme la « récursion ») avec d’autres arguments. Ce pro- cessus se répètera tant que la boucle appelée retourne des résultats.
1
2 ...
3
4 ...
5
Lorsqu’un site possède de nombreuses sous-rubriques, ou de nombreux messages de forums, ces boucles récursives sont souvent utilisées. On peut ainsi afficher facilement des éléments identiques hiérarchisés. 18 CHAPITRE 1. BOUCLES
1.4.1 Exemple
Nous allons de cee manière afficher la liste complète des rubriques du site. Pour cela, nous bouclons une première fois sur les rubriques, avec un critère pour sé- lectionner les rubriques filles de la rubrique en cours : {id_parent}. Nous trions aussi par numéro (un rang donné aux rubriques pour les afficher volontairement dans un certain ordre), puis par titre de rubrique.
1
2
- #TITRE
5 ^^I
6
3
4
7
8
9
Au premier passage dans la boucle, id_parent va lister les rubriques à la racine du site. Elles ont le champ SQL id_parent valant zéro. Une fois la première rubrique affichée, la boucle récursive est appelée. SPIP appelle de nouveau la boucle « _rubs ». Cee fois la sélection {id_parent} n’est plus la même car ce critère liste les rubriques filles de la rubrique en cours. S’il y a effectivement des sous-rubriques, la première est affichée. Puis aussitôt et une nouvelle fois, mais dans cee sous-rubrique, la boucle « _rubs » est exécutée. Tant qu’il y a des sous rubriques à afficher, ce processus récursif recommence. Ce qui donne :
1
- en
3 ^^I
- Introduction
- The templates
6 ^^I^^I^^I
- Loops
7 ^^I^^I^^I^^I
8 ^^I^^I^^I
9 ^^I^^I
- Extending SPIP
11 ^^I^^I^^I
- Introduction
- Pipelines
12 ^^I^^I^^I^^I
13 ^^I^^I^^I^^I
14 ^^I^^I^^I^^I...
15 ^^I^^I^^I
16 ^^I^^I
4 ^^I^^I
5 ^^I^^I
10 ^^I^^I
17 ^^I^^I...
18 ^^I
19
- fr
21 ^^I
- Introduction
- Écriture des squelettes
24 ^^I^^I^^I
- Boucles
- Balises
- Critères de boucles
25 ^^I^^I^^I^^I
26 ^^I^^I^^I^^I
27 ^^I^^I^^I^^I
28 ^^I^^I^^I^^I...
29 ^^I^^I^^I
30 ^^I^^I
22 ^^I^^I
23 ^^I^^I
31 ^^I^^I...
32 ^^I
33
2
20
34
1.4.2 En savoir plus !
Comprendre les principes de la récursivité en programmation n’est pas forcément facile. Si ce qui est expliqué ici vous laisse perplexe, li- sez l’article consacré de SPIP.net qui explique cela avec d’autres mots : hp ://www.spip.net/fr_article914.html 20 CHAPITRE 1. BOUCLES 1.5 Boucle sur une table absente
Lorsqu’on demande à SPIP d’interroger une table qui n’existe pas, celui-ci affiche une erreur sur la page pour tous les administrateurs du site. Cependant cee absence peut être parfois justifiée, par exemple si l’on interroge une table d’un plugin qui peut être actif ou non. Pour cela un point d’interroga- tion placé juste avant la fin de la parenthèse permet d’indiquer que l’absence de la table est tolérée :
1
2 ...
3
1.5.1 Exemple
Si un squelee utilise le plugin « Agenda » (qui propose la table EVENEMENTS), mais que ce squelee doit fonctionner même en absence du plugin, il est possible d’écrire ses boucles :
1
2 ...
3 21
Chapitre 2
Balises
Les balises servent la plupart du temps à afficher ou calculer des contenus. Ces contenus peuvent provenir de différentes sources :
• de l’environnement du squelee, c’est à dire de certains paramètres trans- mis au squelee ; on parle alors de contexte de compilation.
• du contenu d’une table SQL à l’intérieur d’une boucle
• d’une autre source spécifique. Dans ce cas là, les balises et leurs actions doivent obligatoirement être indiquées à SPIP alors que les 2 sources pré- cédentes peuvent être calculées automatiquement.
2.1 Syntaxe complète des balises
Comme les boucles, les balises ont des parties optionnelles, et peuvent avoir des arguments. Les étoiles annulent des traitements automatiques.
1 #BALISE
2 #BALISE{argument}
3 #BALISE{argument, argument, argument}
4 #BALISE*
5 #BALISE**
6 [(#BALISE)]
7 [(#BALISE{argument})] 22 CHAPITRE 2. BALISES
8 [(#BALISE*{argument})]
9 [ avant (#BALISE) apres ]
10 [ avant (#BALISE{argument}|filtre) apres ]
11 [ avant (#BALISE{argument}|filtre{argument}|filtre) apres ]
12 ...
2.1.1 Règle de croets
L’écriture complète, avec parenthèses et crochets est obligatoire dès lors qu’un des arguments de la balise utilise aussi parenthèses et crochets ou lorsque la balise contient un filtre.
1 // risque de mauvaises surprises :
2 #BALISE{[(#BALISE|filtre)]}
3 // interpretation toujours correcte :
4 [(#BALISE{[(#BALISE|filtre)]})]
5 // bien que cette ecriture fonctionne en SPIP 2.0, elle n’est pas garantie :
6 #BALISE{#BALISE|filtre}
7 // l’utilisation d’un filtre exige crochets et parentheses :
8 [(#BALISE|filtre)]
2.1.2 Exemple
Afficher un lien vers la page d’accueil du site :
Afficher une balise HTML
et le contenu d’un #SOUSTITRE s’il existe :
1 [
On appelle environnement l’ensemble des paramètres qui sont transmis à un squelee donné. On parlera aussi de contexte de compilation. Par exemple, lorsqu’un visiteur demande à afficher l’article 92, l’identifiant de l’article (92) est transmis au squelee article.html. A l’intérieur de ce squelee là, il est possible de récupérer cee valeur grâce à une balise spéciale : #ENV. Ainsi #ENV{id_article} afficherait ”92”. Certains paramètres sont automatiquement transmis au squelee, comme la date actuelle (au moment du calcul de la page) affichable avec #ENV{date}. De la même manière, si l’on appelle un squelee avec des arguments dans l’URL de la page, ceux-ci sont transmis à l’environnement.
2.2.1 Exemple
L’URL spip.php?page=albums&type=classique va charger un squelee albums.html. Dedans, #ENV{type} permera de récupérer la valeur transmise, ici « classique ».
2.3 Contenu des boucles
Le contenu extrait des sélections réalisées avec des boucles SPIP est affiché grâce à des balises. Automatiquement, lorsqu’une table possède un champ SQL « x », SPIP pourra afficher son contenu en écrivant #X.
1
2 #X - #NOM_DU_CHAMP_SQL - #CHAMP_INEXISTANT
3
SPIP ne créera pas de requête SQL de sélection totale (SELECT * ...) pour récupérer les informations demandées, mais bien, à chaque fois, des sélections spécifiques : ici, ce serait SELECT x, nom_du_champ_sql FROM spip_tables. Lorsqu’un champ n’existe pas dans la table SQL, comme ici « champ_inexistant », SPIP ne le demande pas dans la requête, mais essaie alors de le récupérer dans 24 CHAPITRE 2. BALISES
une boucle parente, si il y en a. Si aucune boucle parente ne possède un tel champ, SPIP le cherche alors dans l’environnement, comme si l’on écrivait #ENV{champ_inexistant}.
2.3.1 Exemple
Imaginons une table SQL ”chats” contenant 5 colonnes « id_chat », « race », « nom », « age », « couleur ». On pourra lister son contenu de la sorte :
1
2
Nom | Age | Race |
---|---|---|
#NOM | #AGE | #RACE |
12
Automatiquement, SPIP, en analysant le squelee, comprendra qu’il doit récu- pérer les champs nom, age et race dans la table SQL chats. Cependant, il n’ira pas récupérer les champs dont il n’a pas besoin (ici id_chat et couleur), ce qui évite donc de surcharger le serveur de base de données en demandant des champs inutiles.
2.4 Contenu de boucles parentes
Il est parfois utile de vouloir récupérer le contenu d’une boucle parente de celle en cours, à travers une balise. SPIP dispose d’une écriture pour cela (n étant l’identifiant de la boucle voulue) :
1 #n:BALISE 2.5. BALISES PRÉDÉFINIES 25
2.4.1 Exemple
Afficher systématiquement le titre de la rubrique en même temps que le titre de l’article :
1
2
- #_rubs:TITRE - #TITRE
3
4
5
6
7
2.5 Balises prédéfinies
Nous l’avons vu, nous pouvons extraire avec les balises des contenus issus de l’environnement ou d’une table SQL. Il existe d’autres balises qui ont des actions spéciales explicitement définies. Dans ces cas là, elles sont déclarées (dans SPIP) soit dans le fichier ecrire/public/balises.php, soit dans le répertoire ecrire/balise/ Voici quelques exemples :
• #NOM_SITE_SPIP : retourne le nom du site
• #URL_SITE_SPIP : retourne l’url du site (sans le / final)
• #CHEMIN : retourne le chemin d’un fichier #CHEMIN{javascript/jquery.js}
• #CONFIG : permet de récupérer des informations sur la configuration du site (stockée en partie dans la table SQL « spip_meta »). #CONFIG{version_installee}
• #SPIP_VERSION : affiche la version de SPIP
• … 26 CHAPITRE 2. BALISES
Nous en verrons bien d’autres par la suite.
2.6 Balises génériques
SPIP dispose de moyens puissants pour créer des balises particulières pouvant s’adapter au contexte de la page, de la boucle ou simplement au nom de la balise. Ainsi, il est possible de déclarer des balises qui auront toutes le même préfixe et effectueront ainsi un traitement commun propre à chaque type de balise. Ces types de balises sont déclarées dans le répertoire ecrire/balise/. Ce sont les fichiers *_.php. On trouve ainsi :
• #LOGO_ pour afficher des logos d’article, de rubrique ou autre : #LOGO_ARTICLE
• #URL_ pour déterminer une URL d’un objet SPIP, comme #URL_MOT à l’in- térieur d’une boucle MOTS
• #FORMULAIRE_ pour afficher un formulaire défini dans le répertoire /formulaires tel que #FORMULAIRE_INSCRIPTION
2.7 Traitements automatiques des balises
La plupart des balises SPIP, dont toutes celles issues de la lecture de la base de données effectuent des traitements automatiques pour bloquer des codes mal- veillants qui pourraient être ajoutés par des rédacteurs au moment de l’écriture de l’article (du code PHP ou des scripts JavaScript). En plus de ces traitements, d’autres peuvent être définis pour chaque champ SQL afin de faire appliquer automatiquement les traitements sur le champ en ques- tion. Ces opérations sont définies dans le fichier ecrire/public/interfaces.php par un tableau global $table_des_traitements. La clé du tableau est le nom de la balise, la valeur un tableau associatif :
• sa clé « 0 » (le premier $table_des_traitements[’BALISE’][] rencon- tré) définit un traitement quelle que soit la table concernée, 2.7. TRAITEMENTS AUTOMATIQUES DES BALISES 27
• une clé « nom_de_la_table » ($table_des_traitements[’BALISE’][’nom_de_la_table’] sans le préfixe de table) définit un traitement pour une balise d’une table spécifique.
Les traitements sont donnés par une chaîne de caractères fonction(%s) expli- citant les fonctions à appliquer. Dedans, « %s » sera remplacé par le contenu du champ.
1 $table_des_traitements[’BALISE’][] = ’traitement(%s)’;
2 $table_des_traitements[’BALISE’][’objets’]= ’traitement(%s)’;
Deux usages fréquents des filtres automatiques sont définis par des constantes pouvant être utilisées :
• _TRAITEMENT_TYPO applique les traitements typographiques,
• _TRAITEMENT_RACCOURCIS applique les traitements typographiques et les traductions des raccourcis SPIP.
2.7.1 Exemple
Les balises #TITRE et #TEXTE reçoivent des traitements, qui s’appliquent quelle que soit la boucle, définis de cee façon :
1 $table_des_traitements[’TEXTE’][] = _TRAITEMENT_RACCOURCIS;
2 $table_des_traitements[’TITRE’][] = _TRAITEMENT_TYPO;
La balise #FICHIER effectue un traitement uniquement dans les boucles docu- ments :
1 $table_des_traitements[’FICHIER’][’documents’] = ’get_spip_doc(%s)’; 28 CHAPITRE 2. BALISES 2.8 Empêer les traitements automatiques
Les traitements de sécurité et les traitements définis s’appliquent automatique- ment sur les balises, mais il est possible d’éviter cela pour certaines particularités d’un squelee. L’extension « étoile » d’une balise est conçue pour :
1 // tous les traitements
2 #BALISE
3 // pas les traitements definis
4 #BALISE*
5 // meme pas les traitements de securite
6 #BALISE**
2.8.1 Exemple
Retarder l’application des traitements typographiques et des raccourcis SPIP sur le texte d’une page (le filtre propre est appliqué normalement automatiquement), pour ajouter, avant, un filtre effectuant une action quelconque :
1 [
Chapitre 3
Des balises à connaître
Dans le jeu de balises spécifiques dont dispose SPIP par défaut, un certain nombre sont assez souvent utilisées et doivent donc être mentionnées ici. Nom Description #AUTORISER (p. 40) Tester des autorisations #CACHE (p. 39) Définir la durée du cache #CHEMIN (p. 39) Retrouver l’adresse d’un fichier #DESCRIPTIF_SITE_SPIP (p. 41) Retourner le descriptif du site #EDIT (p. 41) Éditer du contenu (avec le plugin « crayons ») #ENV (p. 38) Récupérer une variable dans l’envi- ronnement #EVAL (p. 43) Évaluer une expression via PHP #EXPOSE (p. 42) Mere en évidence l’élément en cours de lecture (dans une liste, un menu) #GET (p. 36) Récupérer une valeur stockée par #SET #INCLURE (p. 43) Inclure un squelee #INSERT_HEAD (p. 34) Balise d’insertion de scripts dans le
pour SPIP ou des plugins #INSERT_HEAD_CSS (p. 47) Balise d’insertion de CSS dans le pour des plugins. #INTRODUCTION (p. 35) Afficher une introduction #LANG (p. 44) Obtenir le code de langue #LANG_DIR (p. 34) Retourner le sens d’écriture #LESAUTEURS (p. 45) Afficher les auteurs d’un article 30 CHAPITRE 3. DES BALISES À CONNAÎTRENom Description #MODELE (p. 45) Insère un modèle de mise en page #NOTES (p. 32) Afficher les notes crées avec le rac- courci SPIP [[]] #REM (p. 32) Mere un commentaire dans le code #SELF (p. 32) Retourne l’URL de la page courante #SESSION (p. 31) Récupère une information de session #SESSION_SET (p. 46) Définir des variables de session #SET (p. 37) Stocker une valeur, récupérable avec #GET #VAL (p. 30) Retourne une valeur
3.1 #VAL
#VAL{valeur} permet de renvoyer la valeur qu’on lui donne, tout simplement. Cee balise sert principalement pour envoyer un premier argument à des filtres existants.
1 #VAL{Ce texte sera retourne}
3.1.1 Exemple
Retourner un caractère avec la fonction PHP chr :
1 [(#VAL{91}|chr)] // [
2 [(#VAL{93}|chr)] // ]
Parfois le compilateur de SPIP se mélange les pinceaux entre les crochets que l’on souhaite écrire, et les crochets d’ouverture ou de fermeture des balises. Un exemple fréquent est l’envoi d’un paramètre tableau dans un formulaire (name=”champ[]”), lorsque le champ est inclus dans une balise :
1 // probleme : le ] de champ[] est confondu
2 // avec la fermeture de la balise #ENV 3.2. #SESSION 31
3 [(#ENV{afficher}|oui)
4
5 ]
6 // pas de probleme ici
7 [(#ENV{afficher}|oui)
8
9 ]
3.2 #SESSION
#SESSION{parametre} affiche des informations sur le visiteur connecté. Une session peut être considérée comme des informations individuelles, conservées sur le serveur le temps de la visite du visiteur. Ainsi, ces informations peuvent être retrouvées et réutilisées lorsque celui-ci change de page.
La présence de cee balise, comme pour la balise #AUTORISER, génère un cache différent par visiteur authentifié sur le site, et un cache pour les visiteurs non authentifiés.
3.2.1 Exemple
Afficher le nom du visiteur s’il est connu :
1 #SESSION{nom}
Afficher une information si le visiteur est authentifié sur le site, c’est à dire qu’il possède un id_auteur :
1 [(#SESSION{id_auteur}|oui) Vous êtes authentifié ] 32 CHAPITRE 3. DES BALISES À CONNAÎTRE 3.3 #SELF
#SELF retourne l’URL de la page en cours. Cee URL ne peut être calculée correctement dans une inclusion que si le para- mètre self ou env lui est transmis afin de créer un cache différent pour chaque URL.
1
3.4 #REM
#REM permet de commenter du code dans les squelees.
1 [(#REM) Ceci n’est pas une pipe ! Mais un commentaire ]
Note : Le code contenu dans la balise est tout de même interprété par SPIP, mais rien n’est affiché. Un filtre qui se trouve dedans sera effectivement appelé (ce qui n’est pas forcément ce que l’on souhaite) :
1 [(#REM|filtre)]
2 [(#REM) [(#BALISE|filtre)] ]
3.5 #NOTES
#NOTES affiche les notes (renvois en bas de page) qui ont été calculées par l’affi- chage des balises précédentes. Ainsi si une balise, dont on calcule les raccourcis SPIP avec le filtre propre, ou avec un traitement automatique, contient des notes, elles pourront être affichées avec #NOTES, après leur calcul.
1 [(#BALISE|propre)]
2 #TEXTE
3 #NOTES 3.5. #NOTES 33
3.5.1 Précisions sur les notes
C’est la fonction traiter_raccourcis() appelée par le filtre propre qui exé- cute une fonction (inc_notes_dist() du fichier ecrire/inc/notes.php qui stocke temporairement les notes en mémoire. Dès que la balise #NOTES est appelée, ces notes sont retournées et vidées de la mémoire. Imaginons un texte dans le « chapo » et le « texte » d’un article comme cela :
1 // chapo :
2 Dans le chapo, une note [[Note A]] et une autre [[Note B]]
3 // texte :
4 Dans le texte, une note [[Note C]] et une autre [[Note D]]
Lors de l’affichage dans un squelee, les deux syntaxes ci-dessous produiront des contenus différents. La première affichera toutes les notes numérotées de 1 à 4 après le contenu du texte :
1
2 #CHAPO
3 #TEXTE
4 #NOTES
5
Dans cee seconde écriture, les notes du « chapo » sont d’abord affichées (numé- rotées de 1 à 2) après le contenu de #CHAPO, puis les notes du texte (numérotées aussi de 1 à 2), après le contenu de #TEXTE :
1
2 #CHAPO
3 #NOTES
4 #TEXTE
5 #NOTES
6 34 CHAPITRE 3. DES BALISES À CONNAÎTRE
3.5.2 Exemple
L’appel des notes se fait souvent après l’affichage de tous les autres champs d’un article, cela pour prendre en compte toutes les notes calculées. L’affichage est simple :
1 [
<:info_notes:>
(#NOTES)3.6 #LANG_DIR
#LANG_DIR retourne le sens d’écriture d’un texte en fonction de la langue, soit « ltr » (pour « le to right »), soit « rtl » (pour « right to le »). Comme #LANG, la langue est prise dans la boucle la plus proche ayant un champ « lang », sinon dans l’environnement, sinon dans la langue principale du site. Cee balise est très pratique pour des sites multilingues qui mélangent des langues n’ayant pas le même sens d’écriture.
3.6.1 Exemple
Afficher le texte d’une rubrique dans le sens qui lui convient :
1
2
3
3.7 #INSERT_HEAD
#INSERT_HEAD placé entre les balises HTML
et permet d’ajou- ter automatiquement certains scripts JavaScript. Certains scripts sont ajoutés par défaut par SPIP (jery par exemple), d’autres par des plugins. Se référer aux pi- pelines insert_head (p. 141) et jquery_plugins (p. 153) qui s’occupent d’ajouter 3.8. #INTRODUCTION 35ces scripts. Pour ajouter des CSS, il est préférable d’utiliser #INSERT_HEAD_CSS et le pipeline insert_head_css (p. 196). Dans les squelees par défaut de SPIP, cee balise est insérée à la fin du squelee squelees-dist/inc-head.html.
3.8 #INTRODUCTION
#INTRODUCTION affiche un extrait du contenu d’un champ SQL « texte » (si la table possède ce champ). Dans le cas des articles, cet extrait est puisé dans le champ « descriptif », sinon dans le « chapo », sinon dans le champ « texte ». L’extrait peut aussi être défini, au moment de la rédaction du contenu, en enca- drant l’introduction souhaitée par des balises
1 #INTRODUCTION{longueur}
3.8.1 Exemple
Donner à la balise HTML meta « description » un texte introductif sur les pages articles (exemple dans squelees-dist/article.html):
1
2 ...
3 []
4 ...
5
Afficher les 10 derniers articles avec une introduction de leur contenu :
1
2 ^^I
<:derniers_articles:>
3 ^^I
6 ^^I^^I^^I
#TITRE
7 ^^I^^I^^I[
(#INTRODUCTION)]8 ^^I^^I
4 ^^I^^I
5 ^^I^^I
9 ^^I^^I
10 ^^I
11
3.9 #GET
#GET{variable} permet de récupérer la valeur d’une variable locale stockée avec #SET{variable, valeur}. Voir aussi #SET (p. 37). Un second argument permet de récupérer une valeur par défaut si le paramètre demandé n’existe pas ou si son contenu est vide.
1 #GET{variable, valeur par d © faut}
3.9.1 Exemple
Si « utiliser_documentation » vaut « oui », le dire :
1 #SET{utiliser_documentation,oui}
2 [(#GET{utiliser_documentation}|=={oui}|oui)
3 ^^IOn utilise la documentation !
4 ]
Afficher un lien vers la page d’accueil du site, sur une image « mon_logo.png » si elle existe, sinon sur « logo.png », sinon sur le logo du site :
1 [(#SET{image,[(#CHEMIN{mon_logo.png}
2 ^^I|sinon{#CHEMIN{logo.png}}
3 ^^I|sinon{#LOGO_SITE_SPIP})]})] 3.10. #SET 37
4 [(#GET{image}
5 ^^I|image_reduire{100})]
Différencier l’absence d’un élément dans l’environnement : définir comme va- leur par défaut #ENV{defaut} lorsque #ENV{activer} n’existe pas. Pour cela, le filtre is_null nous permet de tester que #ENV{activer} n’est pas défini. Si #ENV{activer} existe mais est vide, il sera utilisé. On peut ainsi différencier le cas de l’envoi d’une valeur vide dans un formulaire, comme ci-dessous lorsque la valeur envoyée est celle de l’input « champ_activer_non »
1 [(#SET{valeur,[(#ENV{activer}
2 ^^I|is_null|?{#ENV{defaut},#ENV{activer}})]})]
3
4
5
6
7
8
3.10 #SET
#SET{variable,valeur} permet de stocker des valeurs localement, au sein d’un squelee. Elles sont récupérables, dans le même squelee, avec #GET{variable}. Voir aussi #GET (p. 36).
3.10.1 Exemple
Stocker une couleur présente dans l’environnement, sinon une couleur par dé- faut :
1 #SET{claire,##ENV{couleur_claire,edf3fe}}
2 #SET{foncee,##ENV{couleur_foncee,3874b0}}
3 38 CHAPITRE 3. DES BALISES À CONNAÎTRE
4
5 #contenu h3 {
6 ^^Icolor:[(#GET{claire})];
7 }
8
3.11 #ENV
#ENV{parametre} – nous l’avons vu (L’environnement #ENV (p. 23)) – récupère des variables d’environnement transmises au squelee. Un second argument per- met de donner une valeur par défaut si le paramètre demandé n’est pas présent dans l’environnement ou si son contenu est vide.
1 #ENV{parametre, valeur par d © faut}
La valeur du paramètre récupéré est automatiquement filtrée avec entites_html, qui transforme le texte en entité HTML (< devient ainsi <). Pour éviter cet échappement, on peut utiliser une étoile :
1 #ENV*{parametre, valeur par d © faut}
Enfin, la balise #ENV toute seule retourne un tableau sérialisé de tous les para- mètres d’environnement.
3.11.1 Exemple
Récupérer un identifiant d’article, sinon la chaîne « new » :
1 #ENV{id_article,new}
Afficher tout l’environnement (utile pour débugguer) :
1 [
(#ENV**|unserialize|print_r{1})] 3.12. #CHEMIN 39 3.12 #CHEMIN
#CHEMIN{repertoire/fichier.ext} retourne l’adresse relative d’un fichier dans l’arborescence de SPIP. Lire à ce sujet La notion de chemin (p. 116).
3.12.1 Exemple
Retourner l’adresse du fichier « habillage.css ». S’il existe dans le dossier squelettes/, c’est cee adresse qui sera donnée, sinon ce sera l’adresse du fi- chier présent dans le répertoire squelettes-dist/.
1 #CHEMIN{habillage.css}
Le fichier squelees-dist/inc-head.html l’utilise pour charger la feuille de style correspondante dans la partie
du code HTML. Si le fichier est trouvé, la balise HTML est affichée.1 []
Notons que le filtre direction_css permet d’inverser toute la feuille de style CSS (left par right et inversement) si le contenu du site est dans une langue s’écrivant de droite à gauche.
3.13 #CACHE
#CACHE{duree} permet de définir la durée de validité du cache d’un résultat de calcul d’un squelee, exprimée en secondes. Lorsque cee durée est dépassée, le squelee est calculé de nouveau. Cee balise est généralement placée au tout début des squelees. En son absence, par défaut, la durée est de 24h (défini par la constante _DUREE_CACHE_DEFAUT). 40 CHAPITRE 3. DES BALISES À CONNAÎTRE
3.13.1 Exemple
Définir un cache d’une semaine :
1 #CACHE{3600*24*7}
3.14 #AUTORISER
#AUTORISER permet de tester des autorisations d’accès à du contenu, de gérer des affichages spécifiques pour certains visiteurs. Un chapitre spécifique (Auto- risations (p. 227)) est consacré à cee problématique.
1 [(#AUTORISER{action,objet,identifiant}) Je suis autorisé ]
La présence de cee balise, comme la balise #SESSION génère un cache différent pour chaque visiteur authentifié sur le site, et un cache pour les visiteurs non authentifiés.
3.14.1 Exemple
Tester si un visiteur a le droit
• de voir un article donné,
• de modifier un article donné
1 [(#AUTORISER{voir,article,#ID_ARTICLE}) Je suis autorisé à voir l’article]
2 [(#AUTORISER{modifier,article,#ID_ARTICLE}) Je suis autorisé à modifier l’article] 3.15. #DESCRIPTIF_SITE_SPIP 41 3.15 #DESCRIPTIF_SITE_SPIP
#DESCRIPTIF_SITE_SPIP retourne le descriptif du site défini dans la page de configuration de l’interface privée.
3.15.1 Exemple
Dans la partie
du code HTML, il est ainsi possible de définir la méta « description » avec cee balise, particulièrement utile sur la page d’accueil du site (fichier sommaire.html).1 []
Notons que le filtre couper{150} coupe le contenu à 150 caractères (en évitant de couper un mot en deux) ; le filtre textebrut supprime toute balise HTML.
3.16 #EDIT
#EDIT{nom_du_champ} : cee balise seule, ne fait rien et ne renvoie rien… Mais couplée avec le plugin « crayons », elle permet d’éditer des contenus depuis l’in- terface publique si on y est autorisé. Elle retourne dans ce cas des noms de classes CSS qui seront utilisées par un script jery fourni par ce plugin.
1
3.16.1 Exemple
Pouvoir éditer le champ « titre » :
1
#TITRE
2
#TITRE
42 CHAPITRE 3. DES BALISES À CONNAÎTRE 3.17 #EXPOSE#EXPOSE permet de mere en valeur un résultat dans une liste. Lorsqu’on boucle sur une table et que #ENV{id_table} est présent dans l’environnement, ou #ID_TABLE dans une boucle de niveau supérieur, alors #EXPOSE renverra un code particulier si la boucle passe sur la même valeur d’identifiant. Sa syntaxe est :
1 #EXPOSE{texte si oui}
2 #EXPOSE{texte si oui, texte si non}
3 // expose tout seul renvoie ’on’ ou ’’
4 #EXPOSE
3.17.1 Exemple
Lister les articles de la rubrique en cours, en affectant une classe CSS « on » sur l’article actuel.
1
- #TITRE
2
3
4
5
Résultat :
1
- #AUTORISER
- #ENV
- #EVAL
- #EXPOSE
2
3 ...
4
5
6
7 ...
8
#EVAL{expression}, très peu usité, permet d’afficher un résultat d’une évalua- tion par PHP de l’expression transmise.
3.18.1 Exemple
1 #EVAL{3*8*12}
2 #EVAL{_DIR_PLUGINS}
3 #EVAL{$GLOBALS[’meta’]}
3.19 #INCLURE
#INCLURE permet d’ajouter le résultat d’une inclusion dans le squelee en cours. On parle d’inclusion « statique » car le résultat de compilation est ajouté au squelee en cours, dans le même fichier de cache. Cee balise est donc différente d’une inclusion « dynamique » avec
1 // ecriture a preferer
2 [(#INCLURE{fond=nom_du_squelette, argument, argument=xx})]
3 // autre ecriture comprise, mais a eviter
4 [(#INCLURE{fond=nom_du_squelette}{argument}{argument=xx})]
Si du point de vue du résultat visible, utiliser
3.19.1 Exemple
Ajouter au squelee en cours le contenu résultant de la compilation du squelee « inc-navigation.html », auquel on passe le contexte « id_rubrique »
1 [(#INCLURE{fond=inc-navigation, id_rubrique})]
Nota : les inclusions inc-head, inc-navigation des squelees par défaut de SPIP sont appelées par des inclusions dynamiques, et non statiques comme cet exemple.
3.20 #LANG
#LANG affiche le code de langue, pris dans l’élément le plus proche de la balise. Si la balise est placée dans une boucle, #LANG renverra le champ SQL « lang » de la boucle s’il existe, sinon, celui de la rubrique parente, sinon celui de l’environne- ment (#ENV{lang}), sinon la langue principale du site (#CONFIG{langue_site}).
#LANG* permet de ne retourner que la langue d’une boucle ou de l’environne- ment. Si aucune n’est définie, la balise ne renvoie alors rien (elle ne retourne donc pas la langue principale du site).
3.20.1 Exemple
Définir la langue dans la balise HTML de la page :
1 xml:lang=”#LANG” lang=”#LANG” dir=”#LANG_DIR”>
Définir la langue dans un flux RSS (exemple issu de squelees- dist/backend.html):
1 2 ^^Ixmlns:dc=”http://purl.org/dc/elements/1.1/” 3.21. #LESAUTEURS 45 3 ^^Ixmlns:content=”http://purl.org/rss/1.0/modules/content/” 4 > 5 6 ^^I
7 ^^I...
8 ^^I
9 ^^I
10 ^^I...
11
12
3.21 #LESAUTEURS
#LESAUTEURS affiche la liste du ou des auteurs d’un article (ou d’un article syn- diqué), séparés par une virgule. Lorsque le champ SQL « lesauteurs » n’existe pas sur la table demandée, comme sur la table des articles, cee balise charge un modèle de mise en page squelees-dist/modeles/lesauteurs.html.
3.21.1 Exemple
Dans une boucle ARTICLES, indiquer les auteurs :
1 [<:par_auteur:> (#LESAUTEURS)]
3.22 #MODELE
#MODELE{nom} insère le résultat d’un squelee contenu dans le répertoire modeles/. L’identifiant de la boucle parente est transmis par défaut avec le paramètre « id » à cee inclusion. Des arguments supplémentaires peuvent être transmis : 46 CHAPITRE 3. DES BALISES À CONNAÎTRE
1 // ecriture a preferer
2 [(#MODELE{nom, argument=xx, argument})]
3 // autre ecriture comprise, mais a eviter
4 [(#MODELE{nom}{argument=xx}{argument})]
Ces inclusions peuvent aussi être appelées depuis la rédaction d’un article (avec une écriture spécifique) :
1 // XX est l’identifiant de l’objet à transmettre.
2
3 // arguments avec des |
4
3.22.1 Exemple
Lister les différentes langues de traductions d’un article, avec un lien pour y ac- céder :
1
2 #MODELE{article_traductions}
3
3.23 #SESSION_SET
La balise #SESSION_SET{parametre, valeur} permet de définir des variables de session pour un visiteur, qui pourront être récupérées par #SESSION{parametre}.
3.23.1 Exemple
Définir un parfum de vanille ! 3.24. #INSERT_HEAD_CSS 47
1 #SESSION_SET{parfum,vanille}
2 #SESSION{parfum}
3.24 #INSERT_HEAD_CSS
#INSERT_HEAD_CSS placé entre les balises HTML
et permet à des plugins d’ajouter des scripts CSS en utilisant le pipeline insert_head_css (p. 196). Si cee balise n’est pas présente dans le squelee, #INSERT_HEAD ajoutera le contenu du pipeline elle-même. Dans les squelees par défaut de SPIP, cee balise est insérée avant le fichier CSS habillage.css dans squelees-dist/inc-head.html. Ainsi, des thèmes gra- phiques qui surchargent ce fichier habillage.css peuvent également surchar- ger, en CSS, les déclarations ajoutées par les plugins auparavant. 48 CHAPITRE 3. DES BALISES À CONNAÎTRE 49Chapitre 4
Critères de boucles
Les critères de boucles permeent de réaliser des sélections de données parfois complexes.
4.1 Syntaxe des critères
Les critères de boucles s’écrivent entre accolades après le nom des tables.
1
Tout champ SQL dans la table peut devenir un critère de sélection, séparé par un opérateur. Mais d’autres critères peuvent être créés au besoin. Ils sont définis dans le fichier ecrire/public/criteres.php Des balises peuvent aussi être utilisées comme paramètres des critères, mais il n’est pas possible d’utiliser leurs parties optionnelles. Principalement, l’usage des crochets est impossible :
1
2
3
4.1.1 Exemple
Cee boucle ARTICLES dispose de 2 critères. Le premier extrait les articles dont le champ SQL « id_rubrique » de la table SQL « spip_articles » vaut 8. Le second indique de trier les résultats par titre.
1
2 - #TITRE
3
4.2 Critères raccourcis
Un critère peut avoir une écriture simplifiée {critere}. Dans ce cas là, SPIP tra- duit la plupart du temps par {critere=#CRITERE} (sauf si une fonction spéciale a été définie pour le critère en question dans ecrire/public/criteres.php).
1
4.2.1 Exemple
1
Ainsi {id_article} effectue une sélection {id_article=#ID_ARTICLE}. Comme toute balise SPIP, #ID_ARTICLE est récupéré dans les boucles les plus proches s’il existe, sinon dans l’environnement #ENV{id_article}. 4.3. OPÉRATEURS SIMPLES 51 4.3 Opérateurs simples
Tous les critères effectuant des sélections sur des champs SQL disposent d’un certain nombre d’opérateurs.
1 {champ op © rateur valeur}
Voici une liste d’opérateurs simples :
• = : opérateur d’égalité {id_rubrique=8} sélectionne les entrées « id_rubrique » égales à 8.
• > : opérateur de supériorité stricte. {id_rubrique>8} sélectionne les en- trées « id_rubrique » strictement supérieures à 8.
• >= : opérateur de supériorité. {id_rubrique>=8} sélectionne les entrées « id_rubrique » supérieures ou égales à 8.
• < : opérateur d’infériorité stricte. {id_rubrique<8} sélectionne les en- trées « id_rubrique » strictement inférieures à 8.
• <= : opérateur d’infériorité. {id_rubrique<=8} sélectionne les entrées « id_rubrique » inférieures ou égales à 8.
• != : opérateur de non égalité {id_rubrique!=8} sélectionne les entrées « id_rubrique » différentes de 8.
• = : opérateur d’égalité {id_rubrique=8}>
4.4 L’opérateur IN
D’autres opérateurs permeent des sélections plus précises. L’opérateur IN sé- lectionne selon une liste d’éléments. La liste peut être donnée soit par une chaîne séparée par des virgules, soit par un tableau (au sens PHP) retourné par une balise ou un filtre de balise.
1
2
3
L’opérateur inverse, !IN sélectionne les entrées non listées après l’opérateur.
1
4.4.1 Exemple
Sélectionner les images liées à un article :
1
2 - #FICHIER
3
Sélectionner les rubriques, sauf certaines :
1
2 - #TITRE
3
4.5 L’opérateur ==
L’opérateur ==(ou sa négation !== permeent de sélectionner des contenus à partir d’expressions régulières. Ils permeent donc des sélections pouvant être extrêmement précises, mais pouvant aussi être gourmandes en énergie et temps pour le gestionnaire de base de données.
1
2
4.5.1 Exemple
Sélection des titres commençant par « Les » ou « les » :
1
2 - #TITRE
3
Sélection des textes ne contenant pas le mot « carnaval » :
1
2 - #TITRE
3
Sélection des textes contenant « carnaval » suivi, à quelques caractères près (entre 0 et 20), de « Venise ».
1
2 - #TITRE
3
4.6 L’Opérateur «! »
Les critères conditionnels de négation simple, utilisés sur des champs extérieurs à la table (des champs créant une jointure sur une autre table) ne font pas toujours ce que l’on suppose au premier abord.
Ainsi le critère {titre_mot!=rose} sélectionne, sur une boucle ARTICLES tous les articles qui ne sont pas liés au mot clé « rose ». Mais le type de jointure créé fait qu’il sélectionne tous les articles ayant au moins un mot clé, donc au moins un mot clé qui n’est pas « rose ». Or, bien souvent, on cherche simplement à afficher tous les articles n’ayant pas le mot « rose », même ceux qui n’ont aucun mot clé. C’est cela qu’effectue l’opéra- teur {!critere}, qui permet de créer une seconde requête de sélection qui sera utilisée comme critère de sélection de la première : 54 CHAPITRE 4. CRITÈRES DE BOUCLES
1
Dans ce cas précis, les articles ayant un mot clé X sont sélectionnés, puis enlevés de la sélection SQL principale par un NOT IN (requête de sélection). Cee écriture est aussi valable lorsqu’on force un champ de jointure, ainsi on pourrait tout aussi bien écrire :
1
4.6.1 Exemple
Sélectionner les rubriques qui n’ont aucun article dont le titre commence par un « L » ou un « l ». Aention tout de même, cee requête utilisant une expres- sion régulière (^[Ll]) nécessite plus de calculs pour le gestionnaire de bases de données.
1
4.7 Critères optionnels
Parfois il est utile de faire une sélection uniquement si l’environnement contient la balise demandée. Par exemple, on peut souhaiter filtrer des boucles en fonction d’une recherche particulière uniquement si une recherche est effectuée, sinon tout afficher. Dans ce cas, un point d’interrogation permet cela :
1
4.7.1 Exemple
Afficher soit tous les articles du site (si aucune variable id_article, id_rubrique ou recherche n’existe), soit une sélection en fonction des critères présents. Ainsi, si l’on appelle le squelee avec les paramètres id_rubrique=8 et recherche=extra, la boucle sélectionnera simplement les articles répondant à l’ensemble de ces critères.
1
2 - #TITRE
3
4.8 Critères optionnels avec opérateurs
Un cas particulier des critères optionnels est que l’on peut utiliser des opérateurs sous certaines conditions. Il faut que la valeur testée dans l’environnement porte le même nom que le critère tel que le critère X dans : {X ?operateur #ENV{X}}. Tous les opérateurs peuvent s’appliquer, il suffit d’accoler le ? à l’opérateur voulu. Le test est ainsi effectué uniquement si la valeur désignée est présente dans l’environnement, sinon le critère est ignoré.
1
2
3
4
4.8.1 Exemple
Sélectionner les 10 derniers articles ayant une date de rédaction inférieure à celle donnée dans l’environnement, sinon simplement les 10 derniers articles : 56 CHAPITRE 4. CRITÈRES DE BOUCLES
1
- #TITRE
- #TITRE
- Récursivité
- Paramètre
- #TITRE
4 ^^I^^I[(#ENV{afficher_introduction}|=={oui}|oui)
5 ^^I^^I^^I
#INTRODUCTION6 ^^I^^I]
7 ^^I
- #TITRE : #LANG
6
7
- #TITRE : #LANG
8
9
10
11
12
13
- en : en
4
- Notes about this documentation : en
5
6
7
- fr : fr
9
- Notes sur cette documentation : fr
10
11
12
- [(#LANG|traduire_nom_langue)]
- #TITRE
- #TITRE
2
3
4
5
- 57
Chapitre 5
Filtres de balises
Les filtres permeent de modifier le résultat des balises.
5.1 Syntaxe des filtres
Les filtres s’appliquent sur les balises en utilisant le caractère « | » (pipe). En pratique, ils correspondent à l’appel d’une fonction PHP existante ou déclarée dans SPIP.
1 [(#BALISE|filtre)]
2 [(#BALISE|filtre{argument2, argument3, ...})]
Lorsqu’un filtre « x » est demandé, SPIP cherche une fonction nommée « filtre_x ». Si elle n’existe pas, il cherche « filtre_x_dist », puis « x ». Il exécute alors la fonc- tion qu’il a trouvée avec les arguments transmis. Il est important de comprendre que le premier argument transmis au filtre (à la fonction PHP donc) est le résultat de l’élément à gauche du filtre.
5.1.1 Exemple
Insérer un élément title sur un lien. Pour cela, on utilise les filtres |couper, qui permet de couper un texte à la taille voulue, et |attribut_html, qui permet 58 CHAPITRE 5. FILTRES DE BALISES
d’échapper les apostrophes qui pourraient gêner le code HTML généré (exemple : title=’à tire d’ailes’ poserait problème à cause de cee apostrophe.).
Le filtre |couper s’applique sur le résultat de la balise #TITRE, le filtre |attribut_html sur le résultat du filtre |couper. On peut donc chaîner les filtres.
5.2 Filtres issus de classes PHP
Une écriture peu connue permet aussi d’exécuter des méthodes d’une classe PHP. Si l’on demande un filtre « x ::y », SPIP cherchera une classe PHP « filtre_x » possédant une fonction « y » exécutable. S’il ne trouve pas, il cherchera une classe « filtre_x_dist » puis enfin une classe « x ».
1 [(#BALISE|class::methode)]
Exemple Imaginons une classe PHP définie comme ci-dessous. Elle contient une fonction (récursive par ailleurs) qui permet de calculer une factorielle (x! = x*(x-1)*(x- 2)*...*3*2*1).
1 class Math{
2 function factorielle($n){
3 if ($n==0)
4 return 1;
5 else
6 return $n * Math::factorielle($n-1);
7 }
8 }
Elle peut être appelée comme ceci :
1 [(#VAL{9}|Math::factorielle)]
2 // renvoie 362880 5.3. FILTRES DE COMPARAISON 59 5.3 Filtres de comparaison
Comme sur les critères de boucle, des filtres de comparaison sont présents. Ils s’utilisent de la sorte :
1 [(#BALISE|operateur{valeur})]
Voici une liste d’opérateurs :
• == (vérifie une égalité)
• !=
• >
• >=
• <
• <=
5.3.1 Exemple
1 [(#TITRE|=={D © gustation}|oui)
2 ^^ICeci parle de dégustation !
3 ]
4 [(#TEXTE|strlen|>{200}|oui)
5 ^^ICe texte a plus de 200 caractères !
6 ]
Le filtre |oui permet de cacher le résultat du test. En son absence, [(#TITRE|=={Dégustation}) ici ] afficherait, si le test était vrai « 1 ici » (1 signifiant dans ce cas ”vrai”, ou true en PHP) 60 CHAPITRE 5. FILTRES DE BALISES 5.4 Filtres de reere et de remplacement
D’autres filtres permeent d’effectuer des comparaisons ou des recherches d’élé- ments. C’est le cas des filtres « |match » et « |replace »
• match permet de tester si l’argument reçu vérifie une expression régulière transmise en second argument du filtre.
• replace permet de remplacer du texte, en suivant aussi une expression régulière.
1 [(#BALISE|match{texte})]
2 [(#BALISE|replace{texte,autre texte})]
Ces filtres acceptent également deux paramètres supplémentaires qui sont le mo- dificateur éventuel de l’expression régulière (par défaut « UimsS »), et le numéro de la parenthèse capturante qui est par défaut « 0 » (zéro) :
1 [(#BALISE|match{texte, modificateur, capture})]
2 [(#BALISE|replace{texte,autre texte, modificateur, capture})]
5.4.1 Exemple
1 // affiche ”texte oui”
2 [(#VAL{Ce texte est joli}|match{texte}) oui ]
3 // affiche ”oui”
4 [(#VAL{Ce texte est joli}|match{texte}|oui) oui ]
5 // n’affiche rien
6 [(#VAL{Cet © cureuil est joli}|match{texte}) non ]
7 // affiche ”oui”
8 [(#VAL{Cet © cureuil est joli}|match{texte}|non) oui ]
9
10 // affiche ”Ce chat est joli”
11 [(#VAL{Ce texte est joli}|replace{texte,chat})] 5.5. LES FILTRES DE TEST 61 5.5 Les filtres de test
D’autres filtres de test et de logique existent. On trouvera les filtres «? », « si- non », « oui », « non », « et », « ou », « xou » qui permeent permeent de répondre à la plupart des besoins.
• |?{vrai,faux} retourne ”faux” si ce qui entre dans le filtre est vide ou nul, sinon ”vrai”.
• |sinon{ce texte} retourne ”ce texte” seulement si ce qui entre dans le filtre est vide, sinon, retourne simplement l’entrée.
• |oui retourne un espace ou rien. C’est équivalent à |?{’ ’,’’} ou |?{’ ’} et permet de retourner un contenu non vide (un espace) pour signaler que les parties optionnelles des balises doivent s’afficher.
• |non est l’inverse de |oui et est équivalent à |?{’’,’ ’}
• |et permet de vérifier la présence de 2 éléments
• |ou vérifie la présence d’un des deux éléments
• |xou vérifie la présence d’un seul de deux éléments.
Par ailleurs, SPIP comprendra les équivalent anglais « yes », « not », « or », « and » et « xor »
5.5.1 Exemple
1 // affiche le chapeau s’il existe, sinon le début du texte
2 [(#CHAPO|sinon{#TEXTE|couper{200}})]
3 // affiche ”Ce titre est long” seulement si le titre fait plus de 30 caracteres
4 [(#TITRE|strlen|>{30}|oui) Ce titre est long ]
5
6 [(#CHAPO|non) Il n’y a pas de chapo ]
7 [(#CHAPO|et{#TEXTE}) Il y a un chapo, et un texte ]
8 [(#CHAPO|et{#TEXTE}|non) Il n’y a pas les deux ensemble ]
9 [(#CHAPO|ou{#TEXTE}) Il y a soit un chapo, soit un texte, soit les deux ] 62 CHAPITRE 5. FILTRES DE BALISES
10 [(#CHAPO|ou{#TEXTE}|non) Il y a ni chapo, ni texte ]
11 [(#CHAPO|xou{#TEXTE}) Il y a soit un chapo, soit un texte (mais pas les deux, ni aucun) ]
12 [(#CHAPO|xou{#TEXTE}|non) Il y a soit rien, soit tout, mais pas l’un des deux ] 63
Chapitre 6
Inclusions
Pour faciliter la maintenance des squelees générés, il est important de mutua- liser les codes identiques. Cela se réalise grâce aux inclusions.
6.1 Inclure des squelettes
Créer des inclusions, c’est à dire des morceaux de codes précis, permet de mieux gérer la maintenance de ses squelees. Dans la pratique, certaines parties d’une page HTML de votre site vont être identiques quel que soit le type de page. C’est souvent le cas de l’affichage d’un portfolio, d’un menu de navigation, de la liste des mots clés aachés à une rubrique ou un article, etc. Tout squelee SPIP existant peut être inclus dans un autre par la syntaxe sui- vante :
1
6.2 Transmettre des paramètres
Vous pouvez transmere des paramètres aux inclusions. Par défaut, rien n’est transmis à une inclusion hormis la date du calcul. Pour passer des paramètres au contexte de compilation du squelee, il faut explicitement les déclarer lors de l’appel à l’inclusion : 64 CHAPITRE 6. INCLUSIONS
1
2
Le premier exemple avec {param} seul récupère la valeur de #PARAM et la trans- met au contexte de compilation dans la variable param. Le second exemple ari- bue une valeur spécifique à la variable param. Dans les deux cas, dans le squelee appelé, nous pourrons récupérer #ENV{param}.
6.2.1 Transmettre tout le contexte en cours
Le paramètre {env} permet de transmere le contexte de compilation du sque- lee en cours à celui inclus.
6.2.2 Exemple
1 // fichier A.html
2
3 // fichier B.html
4
5 // fichier C.html
6 Type : #ENV{type}
7 Mot : #ENV{mot}
8 Couleur : #ENV{couleur}
Si l’on appelle la page spip.php?page=A&type=animal, celle-ci transmet les pa- ramètres type et mot au squelee B.html. Celui-ci transmet tout ce qu’il reçoit et ajoute un paramètre couleur en appelant le squelee C.html.
Dans le squelee C.html, on peut alors récupérer tous les paramètres transmis. 65
Chapitre 7
Ajax
SPIP permet de recharger simplement des éléments de page en AJAX.
7.1 Paginations AJAX
Les inclusions qui possèdent le critère {ajax} permeent de recharger dans la page seulement la partie incluse. La plupart du temps, il faudra aussi inclure le critère {env} dès lors qu’il y a une pagination dans l’inclusion.
1
Lorsque l’on couple ce critère d’inclusion avec la balise #PAGINATION, les liens de pagination deviennent alors automatiquement AJAX. Plus précisément, tous les liens du squelee inclus contenus dans une classe CSS pagination.
1
#PAGINATION
7.1.1 Exemple
Lister les derniers articles. Cee inclusion liste les derniers articles par groupe de 5 et affiche un bloc de pagination. 66 CHAPITRE 7. AJAX
1
Fichier modeles/liste_derniers_articles.html :
1
2 #ANCRE_PAGINATION
3
4
5
6
7
8
#PAGINATION
9
Résultat : Une pagination ajax, de 5 en 5…
2
3 ^^I
4 ^^I
5 ^^I...
6
7
8 ^^I0
9 ^^I|
10 ^^I5
11 ^^I|
12 ^^I10
13 ^^I|
14 ^^I...
15 ^^I...
16
7.2. LIENS AJAX 67 7.2 Liens AJAXOutre les inclusions contenant une pagination, il est possible de spécifier des liens à recharger en AJAX en ajoutant dessus la classe CSS ajax.
7.2.1 Exemple
1
Fichier modeles/liste_articles.html : Afficher ou cacher l’introduction des articles :
1
2
3 ^^I
8
9
10 [(#ENV{afficher_introduction}|=={oui}|oui)
12 ^^ICacher les introductions
13 ]
14 [(#ENV{afficher_introduction}|=={oui}|non)
16 ^^IAfficher les introductions
17 ] 68 CHAPITRE 7. AJAX 69
Chapitre 8
Éléments linguistiques
La création d’espaces multilingues est toujours une chose délicate à gérer. Nous allons voir dans cee partie comment obtenir des éléments d’interface multi- lingue. SPIP dispose pour gérer les textes des interfaces (à distinguer des contenus édi- toriaux donc) de deux éléments : les chaînes de langues appelées idiomes et la balise multilingue appelée polygloe.
8.1 Syntaxe des aînes de langue
Les chaînes de langue, nommées « idiomes » dans SPIP, sont des codes dont les traductions existent dans des fichiers stockés dans les répertoires lang/ de SPIP, des plugins ou des dossiers squelees. Pour appeler une chaîne de langue, il faut simplement connaître son code :
1 <:bouton_ajouter:>
2 <:navigation:>
La syntaxe générale est celle-ci :
1 <:cle:>
2 <:prefix:cle:> 70 CHAPITRE 8. ÉLÉMENTS LINGUISTIQUES 8.2 Fiiers de langues
Les fichiers de langue sont stockés dans les répertoires lang/. Ce sont des fichiers PHP nommés par un préfix et un code de langue : prefixe_xx.php.
8.2.1 Contenu des fiiers
Ces fichiers PHP déclarent un tableau associatif. À chaque clé correspond une va- leur. Tous les codes problématiques sont échappés (accents), et certaines langues ont des valeurs écrites en signes hexadécimaux (cas du japonais, de l’hébreu…).
1
2 $GLOBALS[$GLOBALS[’idx_lang’]] = array(
3 ^^I’cle’ => ’valeur’,
4 ^^I’cle2’ => ’valeur2’,
5 ^^I// ...
6 );
8.2.2 Exemple
Voici un extrait du fichier de langue du squelee du site Programmer (documentation_fr.php):
1
2 $GLOBALS[$GLOBALS[’idx_lang’]] = array(
3 ^^I//C
4 ^^I’choisir’=>’Choisir...’,
5 ^^I’conception_graphique_par’=>’Thème graphique adapté de ’,
6 ^^I//E
7 ^^I’en_savoir_plus’ => ’En savoir plus !’,
8 ^^I//...
9 ); 8.3. UTILISER LES CODES DE LANGUE 71 8.3 Utiliser les codes de langue
Tout item de langue peut être appelé de la sorte dans un squelee SPIP :
1 <:prefix:code:>
8.3.1 Cherer un code dans plusieurs fiiers
Il est possible de chercher un code dans plusieurs fichiers. Par défaut, si le préfixe n’est pas renseigné, SPIP cherche dans les fichiers local_xx.php, puis spip_xx.php, puis ecrire_xx.php. S’il ne trouve pas le code dans la langue demandé, il cherche dans la langue française. S’il ne trouve toujours pas, il affiche le code langue (en remplaçant les soulignés par des espaces). On peut indiquer de chercher dans plusieurs fichiers avec cee syntaxe :
1 <:prefixe1/prefixe2/.../prefixeN:choisir:>
8.3.2 Surarger un fiier de langue
Pour surcharger des items de langue présents dans un fichier de langue de SPIP, par exemple, ecrire/lang/spip_xx.php ou dans un fichier de langue de plugin, lang/prefixe_xx.php, il suffit de créer un fichier squelettes/lang/local_xx.php et d’y insérer les items modifiés ou nouveaux.
8.3.3 Exemple
Choisir la bonne documentation !
1 <:documentation:choisir:>
Si bouton_ajouter n’est pas trouvé dans le fichier de langue « documentation », le chercher dans celui de « spip », sinon de « ecrire » :
1 <:documentation/spip/ecrire:bouton_ajouter:> 72 CHAPITRE 8. ÉLÉMENTS LINGUISTIQUES 8.4 Syntaxe complète des codes de langue
La syntaxe complète est la suivante :
1 <:prefixe:code{param=valeur}|filtre{params}:>
8.4.1 Paramètres
Les codes de langue peuvent recevoir des paramètres qui seront insérés dans les valeurs au moment de la traduction. Les paramètres sont alors écrits dans les fichiers de langue entre signe arobase (@). Un code de langue pourrait donc être :
1 ’creer_fichier’=>’Créer le fichier @fichier@ ?’,
8.4.2 Appel des paramètres
On appelle ce paramètre comme indiqué :
1 <:documentation:creer_fichier{fichier=tete_de_linote.txt}:>
8.4.3 Filtrer les codes de langue
L’intérêt est assez faible, mais il est possible de passer les codes de langue dans les filtres exactement comme les balises de SPIP, par exemple :
1 <:documentation:longue_description|couper{80}:>
8.5 Codes de langue en PHP
Une fonction existe en PHP pour récupérer les traductions des codes de langue : _T. Elle s’utilise très simplement comme ceci : 8.5. CODES DE LANGUE EN PHP 73
1 _T(’code’);
2 _T(’prefixe:code’);
3 _T(’prefixe1/.../prefixeN:code’);
4 _T(’prefixe:code’, array(’param’=>’valeur’));
8.5.1 Chaînes en développement
Vous trouverez enfin parfois la fonction _L, qui signifie : « Chaîne à mere en code de langue quand le développement sera fini ! ». En gros, pendant les phases de développement de SPIP ou de plugins, les chaînes de langues évoluent souvent. Pour éviter de mélanger les chaînes correctement traduites et les nouvelles qui vont évoluer, la fonction _L est utilisée.
1 _L(’Ce texte devra être traduit !’);
Lorsque le développement est stabilisé, un parcours du code à la recherche des « _L » permet de remplacer alors les chaînes par des codes de langue appropriés (en utilisant alors la fonction _T).
8.5.2 Exemple
Le plugin « Tickets » possède un fichier de langue lang/tickets_fr.php conte- nant (entre autre) :
1 $GLOBALS[$GLOBALS[’idx_lang’]] = array(
2 ^^I// ...
3 ^^I’ticket_enregistre’ => ’Ticket enregirtré’,
4 );
Lorsque l’on crée un nouveau ticket, le retour du formulaire indique que celui-ci a bien été enregistré en transmeant la chaîne de langue au paramètre message_ok du formulaire d’édition de tickets :
1 $message[’message_ok’] = _T(’tickets:ticket_enregistre’);
2 // soit = ”Ticket enregistré” si on est en francais. 74 CHAPITRE 8. ÉLÉMENTS LINGUISTIQUES 8.6 Les Polyglottes (multi)
Une balise (au sens HTML cee fois)
1
Elle permee donc d’écrire à l’intérieur des squelees des éléments multilingues facilement, sans passer par les codes et chaînes de langue.
8.6.1 Utilisation par les rédacteurs
Cee écriture est surtout utilisée par les rédacteurs (ou via un plugin de saisie plus adapté !) pour traduire un site lorsqu’il y a peu de langues (2 ou 3) à traduire.
Chapitre 9
Multilinguisme
SPIP est capable de gérer un site multilingue. On peut entendre deux choses par multilingue :
• avoir la langue de l’interface qui s’adapte au visiteur, par exemple pour afficher les dates ou pour le sens de lecture,
• avoir des contenus en plusieurs langues, et non uniquement l’interface, comme par exemple avoir une version du site en français et une autre en anglais, ou pouvoir traduire des articles déjà rédigés dans une langue vers une autre langue,
• ou pourquoi pas un mélange des deux (interface en arabe avec des textes en français…)
SPIP possède une syntaxe et différents outils pour gérer le multilinguisme.
9.1 Différents multilinguismes
Il y a de nombreuses possibilités pour développer un site multilingue sous SPIP, par exemple :
• créer un secteur (rubrique à la racine du site) par langue, avec des contenus autonomes, 76 CHAPITRE 9. MULTILINGUISME
• créer le site dans une langue principale et déclarer des traductions des ar- ticles dans les différentes langues souhaitées,
• ou encore définir la langue de chaque rubrique du site ou de chaque ar- ticle…
Chaque solution a ses avantages et ses inconvénients et ce choix éditorial in- fluencera quelque peu l’écriture des squelees. Nous allons voir de quels outils disposent les squelees pour les sites multilingues.
9.1.1 En savoir plus !
Un excellent dossier sur le multilinguisme a été réalisé par Alexandra Gui- derdoni pour la SPIP Party de Clermont-Ferrand en 2007. Sa lecture sera bénéfique pour comprendre les subtilités et se poser les bonnes questions lors de la réalisation d’un site multilingue : http://www.guiderdoni.net/ SPIP-et-le-multilinguisme.html
9.2 La langue de l’environnement
SPIP transmet au premier squelee la langue demandée par le visiteur du site que l’on peut récupérer via #ENV{lang} dans un squelee. Par défaut, ce se- ra la langue principale du site, qu’il est possible de modifier avec le formulaire #MENU_LANG qui liste les langues prévues pour le multilinguisme de votre site.
Lorsqu’on qu’on utilise le formulaire #MENU_LANG, la langue sélectionnée est conservée dans un cookie et une redirection est effectuée sur la page en cours avec le paramètre d’URL lang défini sur la langue choisie. Le paramètre lang ainsi transmis va pouvoir être utilisé par SPIP. Il sera aussi possible d’utiliser ultérieurement le cookie pour forcer la langue d’affichage. La langue peut par ailleurs être définie de façon précise lors de l’inclusion d’un squelee en utilisant le paramètre lang :
1
Certains objets éditoriaux de SPIP, c’est le cas des rubriques et des articles, pos- sèdent un champ de langue dans leur table SQL permeant d’indiquer en quelle langue ils sont rédigés (ou à quelle langue ils appartiennent).
On récupère la langue de la rubrique ou de l’article en cours par #LANG dans une boucle RUBRIQUES ou ARTICLES. Lorsque la rubrique en cours n’a pas de langue précise affectée, c’est celle de sa rubrique parente qui est utilisée, sinon la langue principale du site.
9.3.1 Exemple
Affiche les articles et les langues des 2 premières rubriques du site :
1 Votre langue : #ENV{lang}
2
3
4
5
14
15
16
Résultat :
1 Votre langue : fr
2
- 78 CHAPITRE 9. MULTILINGUISME
3
8
13
9.4 Critères spécifiques
Des critères de boucles spécifiques permeent de récupérer les articles dans les langues souhaitées.
9.4.1 lang
Déjà, simplement le critère {lang} permet de sélectionner la langue du visiteur, ou la langue choisie :
1 // langue du visiteur
2
3 // langue anglaise (en)
4
9.4.2 traduction
Le critère {traduction} permet de lister les différentes traductions d’un article :
1
2
- 9.4. CRITÈRES SPÉCIFIQUES 79
3
4
5
6
7
Ici, toutes les traductions d’un article seront affichées (y compris l’article en cours, que l’on peut enlever avec le critère {exclus}).
9.4.3 origine_traduction
Ce critère permet de retrouver les sources d’un article traduit, c’est à dire celui servant de référence aux traductions. Tous les articles sources :
1
2 #TITRE (#LANG)
3
La traduction d’origine d’un article :
1
2
3 #TITRE (#LANG)
4
5
9.4.4 Exemple
Afficher un article dans la langue du visiteur si possible, sinon dans la langue principale. On commence par lister dans une rubrique, les articles qui servent de source à la création des traductions. Ensuite, on cherche s’il existe une traduction dans la langue demandée par le visiteur. Selon la réponse on affiche le titre de l’article traduit ou de l’article source. 80 CHAPITRE 9. MULTILINGUISME
1
2 ^^I
3 ^^I^^I// si une traduction existe
4 ^^I^^I
5 ^^I
6 ^^I^^I// sinon
7 ^^I^^I
8 ^^I
9
9.5 Forcer la langue selon le visiteur
9.5.1 Le paramètre forcer_lang
Le formulaire #MENU_LANG stocke la langue choisie dans un cookie. Ce cookie peut donc être employé pour réafficher le site dans la langue qu’il avait choisit. Une des manières d’y arriver est de définir la variable globale forcer_lang dans un fichier d’options.
1 $GLOBALS[’forcer_lang’] = true;
Sa présence indique à SPIP de systématiquement rediriger la page demandée en ajoutant le paramètre d’URL lang avec la valeur du cookie de langue s’il existe, sinon la langue principale du site.
Cee globale forcer_lang a cependant aussi une autre action : elle indique en même temps que les chaines de langue de l’interface s’affichent dans la langue du visiteur, et non dans la langue des articles ou rubriques.
9.5.2 Autre utilisation du cookie
Une autre possibilité peut être d’utiliser la préférence de l’utilisateur, mais de ne pas forcément rediriger vers le paramètre d’URL lang, cela en utilisant la fonction set_request de SPIP pour ajouter un paramètre lang calculé que SPIP réutilisera ensuite lorsqu’il appellera la fonction _request. 9.5. FORCER LA LANGUE SELON LE VISITEUR 81
9.5.3 Exemple
L’exemple ci-dessous, issu d’un fichier d’option, calcule la langue à utiliser. Ce calcul, ici se passe en deux temps :
• on analyse si l’URL est de la forme http://nom.domaine/langue/reste_de_l_url, où « langue » peut être un des codes de langues définis du site (« fr », « en » ou « es » par exemple) et dans ce cas précis, on utilise la langue trouvée,
• sinon, la fonction utiliser_langue_visiteur() prend la langue du co- okie, sinon la langue du navigateur.
Enfin, si la langue calculée est différente du cookie, le cookie est recréé.
1 // on ajoute la langue d’origine dans le contexte systematiquement.
2 if (!$langue = _request(’lang’)) {
3 ^^Iinclude_spip(’inc/lang’);
4 ^^I$langues = explode(’,’, $GLOBALS[’meta’][’langues_multilingue’]);
5 ^^I// si la langue est definie dans l’url (en/ ou fr/) on l’utilise
6 ^^Iif (preg_match(’,^’ . $GLOBALS[’meta’][’adresse_site’] . ’/(’ . join(’|’,$langues) . ’)/,’, ’http://’ . $_SERVER[’HTTP_HOST’].$_SERVER[’REQUEST_URI’], $r)) {
7 ^^I^^I$langue = $r[1];
8 ^^I^^Ichanger_langue($langue);
9 ^^I} else {
10 ^^I^^I$langue = utiliser_langue_visiteur();
11 ^^I^^Iif (!in_array($langue, $langues)) {
12 ^^I^^I^^I//$langue = ”en”; // pour ne pas s’embeter !
13 ^^I^^I^^I$langue = $GLOBALS[’meta’][’langue_site’];
14 ^^I^^I}
15 ^^I}
16 ^^I// stocker dans $_GET
17 ^^Iset_request(’lang’, $langue);
18 }
19
20 // stocker la langue en cookie...
21 if ($langue != $_COOKIE[’spip_lang’]) { 82 CHAPITRE 9. MULTILINGUISME
22 ^^Iinclude_spip(’inc/cookie’);
23 ^^Ispip_setcookie(’spip_lang’, $langue);
24 }
9.6 Choix de la langue de navigation
Par défaut, lorsqu’on navigue sur un article anglais, les éléments de l’interface sont traduits en anglais.
En utilisant le formulaire de sélection #MENU_LANG, celui-ci change par défaut les éléments de l’interface et ceux des articles par la langue sélectionnée. Sauf que si nous sommes déjà dans un article d’une certaine langue, par exemple anglais, donc avec l’interface en anglais et le menu de langue qui indique « En- glish », et que l’on demande à afficher le français via le menu de langue, l’URL de la page ajoute un paramètre lang=fr, mais rien ne se passe d’autre, l’article reste en anglais et son interface aussi : en fait, c’est le contexte de l’article qui est alors prioritaire sur ce que demande le visiteur. On peut vouloir à l’inverse, afficher l’interface en français, mais lire l’article an- glais tout de même. Pour que l’interface soit indépendante de la langue de l’ar- ticle/rubrique en cours, il faut définir la variable globale forcer_lang :
1 // forcer la langue du visiteur
2 $GLOBALS[’forcer_lang’]=true;
9.7 Forcer un angement de langue d’interface
Dernier point particulier de multilinguisme, on souhaite parfois avoir un mé- lange de langues entre l’interface et les contenus, mais en gardant une certaine cohérence. Précisément lorsqu’on souhaite afficher les articles dans la langue source si ils n’ont pas encore été traduits, sinon dans la langue de traduction. Dans ce cas là, on doit activer forcer_lang Cependant, lorsque sur l’affichage d’un article, on liste les différentes traductions existantes, par exemple avec le modèle modeles/articles_traductions.html 9.7. FORCER UN CHANGEMENT DE LANGUE D’INTERFACE 83
de SPIP, le lien généré ne changera pas la langue de l’interface, vu que forcer_lang conserve la langue du visiteur. Si l’on désire que le fait de cliquer un lien de traduction implique un change- ment de langue d’interface (dans la même langue que la traduction appelée), il faut éditer le modèle articles_traductions.html ou en créer un nouveau. On utilise alors l’action « converser » permeant de générer un lien particulier qui redirigera sur l’article voulu dans la langue d’interface voulue de la sorte :
1 [(#VAL{converser}
2 ^^I|generer_url_action{[redirect=(#URL_ARTICLE
3 ^^I^^I|parametre_url{var_lang,#LANG})]})]
9.7.1 Exemple de modèle complet (et complexe !) :
Ceci est un modèle qui liste les différentes traductions d’un article. Si ce n’est pas la traduction en cours de lecture, un lien est proposé qui indique la langue de traduction.
1
2
3 ^^I(#TOTAL_BOUCLE|>{1}|?{’ ’})
4 ^^I
10 ^^I
11 ]
12 84 CHAPITRE 9. MULTILINGUISME 85
Chapitre 10
Liaisons entre tables (jointures)
Une jointure, en langage SQL est ce qui permet d’obtenir des informations de plusieurs tables réunies en une seule requête. Il est possible de réaliser quelques jointures avec le langage de boucle de SPIP.
10.1 Jointures automatiques
Lorsque dans une boucle il est demandé un critère qui n’appartient pas à la table de la boucle, SPIP essaie automatiquement de trouver une table liée qui contient le champ demandé. SPIP a deux manières de trouver les tables liées : soit les liaisons sont explicite- ment déclarées, soit elles sont calculées.
10.1.1 Exemple
Récupérer les documents qui sont insérés dans les textes des articles ou autre objet éditorial (par un modèle
1
2 - #FICHIER
86 CHAPITRE 10. LIAISONS ENTRE TABLES (JOINTURES)
3
10.2 Déclarations de jointures
Les liaisons entre tables sont déclarées dans SPIP dans le fichier ecrire/public/interfaces.php. D’autres déclarations peuvent être ajoutées avec le pipeline « declarer_tables_interfaces ». Cee déclaration peut-être :
1 // proposer une jointure entre les rubriques et les documents
2 $tables_jointures[’spip_rubriques’][]= ’documents_liens’;
3 // proposer une jointure entre articles et auteurs, en specifiant le champ de la jointure
4 $tables_jointures[’spip_articles’][’id_auteur’]= ’auteurs_articles’;
Cela indique des liaisons possibles entre tables. Lorsque 2 tables peuvent avoir plusieurs champs qui peuvent se lier, on peut indiquer précisément le champ de la liaison.
10.2.1 Exceptions
Il est même possible de créer des jointures lors d’appel à des champs inexistants, par exemple l’appel au critère {titre_mot=yy} peut conduire à une jointure sur la table « spip_mots » alors même que le champ SQL « titre_mot » n’existe pas dans la table de cee manière :
1 $exceptions_des_jointures[’titre_mot’] = array(’spip_mots’, ’titre’);
10.3 Automatisme des jointures
Lorsqu’elles ne sont pas explicitement déclarées à SPIP, les jointures sont cal- culées. Pour cela, SPIP compare entre eux les noms des champs des différentes tables. 10.4. FORCER DES JOINTURES 87
Lorsqu’une boucle, par exemple AUTEURS cherche un critère absent de sa table, par exemple {prenom=Daniel}, SPIP va regarder dans les autres tables qu’il connaît et qui ont des champs homonymes à la table auteur (par exemple la clé id_auteur) si elles possèdent le champ « prenom » demandé. Si l’une d’elles le possède, une jointure sera réalisée entre ces deux tables.
Par exemple, si une table AUTEURS_ELARGIS existe (plugin « Inscription 2 ») avec les champs « id_auteur » et « prenom », une jointure serait réalisée.
10.3.1 objet, id_objet
SPIP 2.0 introduit une nouvelle recherche de jointure. Les clés primaires d’une table, dans ce cas « id_auteur » de la table spip_auteurs, en plus d’être cher- chées dans des champs homonymes sur d’autres tables, sont aussi cherchées dans les tables possédant le couple de champ « objet » et « id_objet », tel que, ici, « ob- jet=auteur ». C’est par exemple le cas de la table spip_documents_liens.
10.4 Forcer des jointures
La détection automatique par SPIP a parfois des limites et deux syntaxes per- meent de forcer des tables à joindre, ou des critères de tables à utiliser.
1 // forcer une table
2
3 // forcer un champ d’une table
4
10.4.1 Exemple
Ces deux boucles sélectionnent les articles dont un auteur possède un nom conte- nant « lie » (comme « Emilie »).
1
2 - #TITRE / #NOM
88 CHAPITRE 10. LIAISONS ENTRE TABLES (JOINTURES)
3
4
5
6 - #TITRE / #NOM
7
Cependant, une différence de taille existe : actuellement, seule l’écriture déclarant l’ensemble des tables permet de faire afficher une balise #CHAMP d’une autre table. Ainsi, #NOM ne sera renseigné que dans la première boucle. 89
Chapitre 11
Accéder à plusieurs bases de données
SPIP permet de lire très facilement des bases de données existantes, au format MySQL, PostGres ou SQLite, et de présenter leur contenu dans des squelees.
11.1 Déclarer une autre base
Pour accéder à une autre base de données, il faut que SPIP dispose des codes d’ac- cès à la base en question. Actuellement, les bases secondaires déclarées sont cor- rectement gérées en lecture. L’écriture par contre dans ces bases externes n’est pas encore correctement prise en compte en SPIP 2.1. Pour déclarer une autre base de données, deux solutions :
• utiliser l’interface graphique prévue pour (Configuration > maintenance du site > Déclarer une base) • écrire selon la syntaxe prévue un fichier de connexion dans le répertoire config/ (ou le répertoire défini par la constante _DIR_CONNECT).
11.1.1 Fiier de connexion config/xx.php
Pour un fichier de connexion tarabiscote.php, son contenu sera :
1
2 if (!defined(”_ECRIRE_INC_VERSION”)) return; 90 CHAPITRE 11. ACCÉDER À PLUSIEURS BASES DE DONNÉES
3 define(’_MYSQL_SET_SQL_MODE’,true);
4 $GLOBALS[’spip_connect_version’] = 0.7;
5 spip_connect_db(’localhost’,’’,’lutilisateur’,’le passe world’,’tarabiscote’,’mysql’, ’spip’,’’);
6 ?>
On appelle donc une fonction spip_connect_db() avec pour arguments, dans l’ordre :
1. adresse du serveur sql
2. numéro de port pour la connexion si nécessaire
3. nom d’utilisateur
4. mot de passe
5. nom de la base de données
6. type de serveur (mysql, pg, sqlite2, sqlite3…)
7. préfixe des tables
8. connexion des utilisateurs par ldap ?
11.2 Accéder à une base déclarée
Chaque base supplémentaire ainsi déclarée peut-être appelée via les boucles SPIP de cee manière :
1
Le paramètre nom correspond au nom du fichier de connexion. 11.3. LE PARAMÈTRE « CONNECT » 91
11.2.1 Exemple
J’ai testé WordPress il y a quelques temps et j’ai donc une base fonctionnelle. En créant un fichier de connexion wordpress.php il m’est possible de récupérer grâce à cela, les 5 dernières publications comme ceci :
1
2 ^^I
#POST_TITLE
3 ^^I
4
11.3 Le paramètre « connect »
Lorsqu’il n’est pas spécifié de fichier de connexion à utiliser dans les boucles, SPIP utilise le fichier de connexion par défaut (souvent nommé connect.php). Pour toutes ces boucles là, on peut transmere via l’url une connexion particu- lière qui sera alors appliquée en indiquant le paramètre connect=nom.
11.3.1 Exemple
Si vous avez 2 sites SPIP avec deux squelees différents (un site A et un site B). En copiant le fichier de connexion du site A dans le site B (en le renommant en A.php) et inversement, vous pourrez alors naviguer selon les différentes combi- naisons :
• http://A/ (le contenu du site A s’affiche avec le squelee A)
• http://B/ (le contenu du site B s’affiche avec le squelee B)
• http://A/?connect=B (le contenu du site B s’affiche avec le squelee A)
• http://B/?connect=A (le contenu du site A s’affiche avec le squelee B) 92 CHAPITRE 11. ACCÉDER À PLUSIEURS BASES DE DONNÉES
Pour résumer, passer un connect=nom dans l’url permet d’utiliser le fichier de connexion « nom » dans toutes les boucles des squelees qui n’ont pas de connexion définie, comme
11.4 Inclure suivant une connexion
Il est possible de passer une connexion particulière via une inclusion :
1
2 [(#INCLURE{fond=derniers_articles, connect=demo.example.org})]
Une inclusion ne transmet pas automatiquement la connexion parente ; pour pro- pager une connexion il faut la spécifier dans l’inclusion :
1
2 [(#INCLURE{fond=derniers_articles, connect})] Troisième partie
Les différents répertoires
93
11.5. SQUELETTES 95
Ce chapitre explique le rôle des différents répertoires de SPIP.
11.5 squelettes
Le répertoire squelettes, non présent par défaut, permet de surcharger les fi- chiers d’origine de SPIP et de plugins, dont les squelees par défaut. Ce réper- toire permet aussi de créer ses propres squelees et de placer tous les fichiers spécifiques à son site.
11.6 Liste des répertoires
11.7 extensions
Le répertoire extensions permet de définir les plugins installés, actifs et non désactivables, dès l’installation de SPIP. Il suffit de placer les plugins souhaités dans ce répertoire. Dans la distribution de SPIP, des plugins sont présents par défaut :
• « Compresseur », pour compresser les Javascript, CSS et HTML, • « Filtres images et couleurs », donnant accès aux traitements graphiques et typographiques, • « Porte Plume », fournissant une barre d’outils d’édition des raccourcis SPIP, • « SafeHTML », pour neoyer les forums et les flux de syndication d’élé- ments indésirables.
11.8 config
Le répertoire config stocke des informations de configuration relatifs au site, tel que les identifiants de connexion à la base de données (connect.php) ou à des 96 bases externes, le fichier mes_options.php relatif au site ou encore l’écran de sé- curité (ecran_securite.php) permeant de combler rapidement d’éventuelles failles découvertes.
11.9 IMG
Le répertoire IMG/ contient l’ensemble des documents éditoriaux ajoutés par les rédacteurs du site, classés (par défaut) par extension dans des sous répertoires.
11.10 lib
Ce répertoire (non présent par défaut) permet à des plugins de partager des li- brairies externes, qui sont alors téléchargées et extraites dans ce répertoire.
11.11 local
Ce répertoire stocke les caches crées par les images typographiques, les redi- mensionnements d’images, les traitements graphiques, les compressions CSS ou JavaScript ; c’est à dire tous les caches nécessitant un accès HTTP. Lire sur ces sujets :
• Caches CSS et Javascript (p. 260)
• Cache des traitements d’image (p. 261)
11.12 plugins
Le répertoire plugins permet de placer les plugins qui seront activables et désac- tivables dans la page de configuration des plugins de l’espace privé. La présence d’un répertoire plugins/auto accessible en écriture autorise les administrateurs webmestres à télécharger automatiquement des plugins depuis l’interface. 11.13. SQUELETTES-DIST 97 11.13 squelettes-dist
Ce répertoire contient le jeu de squelees fourni avec SPIP. Il contient aussi des formulaires publics et des modèles.
11.14 tmp
Ce répertoire contient les fichiers temporaires, de caches et de log, non acces- sibles par HTTP. On retrouve dedans un dossier spécifique
• pour le cache (cache),
• un autre pour les sauvegardes (dump),
• pour les sessions des visiteurs enregistrés (sessions),
• pour les documents envoyés par FTP (upload)
• ou encore pour calculer les statistiques des visites (visites) 98 99
Chapitre 12 ecrire
Ce répertoire contient tout ce qui fait fonctionner SPIP !
12.1 ecrire/action
Ce répertoire a pour but de réaliser les modifications les contenus dans la base de données. La plupart des actions sont sécurisées, de sorte qu’elles vérifient à la fois :
• que l’auteur effectuant l’action a l’autorisation de l’effectuer,
• que c’est bien la personne connectée qui a demandée cee action en son nom. À la fin des traitements, une redirection est effectuée vers une URL in- diquée en général dans l’appel de l’action. Se référer au chapitre sur les actions et traitements (p. 237) pour plus de détail.
12.2 ecrire/auth
Le répertoire ecrire/auth contient les différents scripts pour gérer la connexion des utilisateurs. Un fichier gère l’authentification via la procédure SPIP, un autre via un annuaire LDAP. 100 CHAPITRE 12. ECRIRE
Les processus d’authentifications sont relativement complexes faisant entrer de nombreuses sécurités. Une API définit les différentes étapes de l’authentification et de la création de nouveaux utilisateurs. Se référer au chapitre sur l’authentifi- cation (p. 243) pour plus de précisions.
12.3 ecrire/balise
Le répertoire ecrire/balise permet de définir
• des balises dynamiques, c’est à dire effectuant un calcul à chaque appel de page,
• des balises génériques, c’est à dire commençant par le même préfixe et effectuant des actions communes (#URL_, #FORMULAIRE_, …) Les balises statiques, elles, sont déclarées dans le fichier ecrire/public/balises.php, ou pour les plugins, dans des fichiers de fonctions. Se reporter au chapitre sur les balises (p. 207) pour des explications dé- taillées.
12.4 ecrire/public
Le mal nommé répertoire ecrire/public contient les différents fichiers rela- tifs à la recherche, l’analyse, la compilation, le débuggage des squelees SPIP, la création des pages issues de squelees squelees et la gestion des caches corres- pondants. Des précisions sur le fonctionnement du compilateur (p. 245) sont présentes dans le chapitre correspondant.
12.5 ecrire/req
Le répertoire ecrire/req contient les traducteurs entre les fonctions d’abstrac- tion SQL de SPIP et les moteurs de base de données correspondants. atre pilotes sont fournis : MySQL, PostGres, SQLite 2 et SQLite 3. 12.6. ECRIRE/TYPOGRAPHIE 101 12.6 ecrire/typographie
Ce répertoire contient les corrections typographiques pour le français et l’an- glais, appliquées lors de l’appel à la fonction typo.
12.7 ecrire/urls
Le répertoire ecrire/urls contient les différents jeux d’URL proposés par SPIP (propre, html, arborescent…). L’API de ces jeux d’URL permet de construire une URL à partir d’un contexte donné et inversement de retrouver un objet et son identifiant à partir d’une URL.
12.8 ecrire/xml
Ce répertoire contient des fonctions pour analyser des chaines XML et les trans- former en tableau PHP. Un outil de vérification est aussi présent et permet de calculer les erreurs de DTD d’une page.
12.9 ecrire/base
Ce dossier contient ce qui est en rapport avec la base de données : les description des tables, les fonctions d’abstraction SQL, les fonctions de création et de mise à jour des tables SQL. Un chapitre complet s’intéresse à la base de données : Accès SQL (p. 301).
12.10 ecrire/arsets
Ce répertoire contient des fichiers servant aux traductions d’encodages de carac- tères, généralement appelés par le fichier ecrire/inc/charsets.php. 102 CHAPITRE 12. ECRIRE 12.11 ecrire/configuration
Ce répertoire contient les éléments des pages de configuration dans l’espace privé de SPIP. Chaque fichier correspond à un cadre particulier de configuration.
12.12 ecrire/exec
Le répertoire ecrire/exec stocke les fichiers PHP permeant d’afficher des pages dans l’espace privé avec le paramètre ?exec=nom. De plus en plus est utili- sé maintenant un affichage utilisant des squelees SPIP pour ces pages, installés dans le répertoire prive/exec (p. 107). Une explication détaillée est donnée dans le chapitre sur la création de pages pour l’espace privé (p. 215).
12.13 ecrire/maj
Ce répertoire contient les procédures de mise à jour de la base de données au fil des versions de SPIP. Pour des versions anciennes, il contient aussi la structure de la base de données d’origine. Cela permet de réimporter des sauvegardes SPIP de version antérieure (jusqu’à SPIP 1.8.3) normalement sans difficulté.
12.14 ecrire/notifications
Ce répertoire contient les différentes fonctions appelées par l’API de notifications de SPIP présente dans le fichier ecrire/inc/notifications.php. Les notifica- tions permeent (par défaut) d’envoyer des emails suite à des évènements sur- venus dans SPIP, comme l’arrivée d’un nouveau message sur un forum. Ce répertoire contient aussi certains squelees SPIP construisant des textes de mails envoyés lors de notifications. 12.15. ECRIRE/PLUGINS 103 12.15 ecrire/plugins
Le répertoire ecrire/plugins contient tout ce qui a un rapport avec les plu- gins de SPIP, ainsi que les extensions (plugins non désactivables) et les librairies externes (répertoire lib/). On trouve donc de quoi lister les plugins présents, dé- terminer leur dépendances, analyser les fichiers plugin.xml, gérer les différents caches en rapport avec les plugins (lire à ce sujet le cache des plugins (p. 259))…
12.16 ecrire/genie
Le répertoire ecrire/genie stocke les fonctions à executer de manière pério- diques par le génie (ce qu’on appelle un cron), à raison, bien souvent d’un fichier par tâche à effectuer. Lire le chapitre à ce sujet : la programmation de tâches périodiques (p. 265).
12.17 ecrire/inc
Ce répertoire contient la plupart des librairies PHP créées pour SPIP. Certaines sont chargées systématiquement. C’est le cas de ecrire/inc/utils.php qui contient les fonctions de base et de démarrage, ou encore ecrire/inc/flock.php s’occupant des accès aux fichiers.
12.18 ecrire/install
Le répertoire ecrire/install contient tout ce qui concerne l’installation de SPIP. Les différents fichiers construisent les étapes d’installation et sont appelés via le fichier ecrire/exec/install.php.
12.19 ecrire/lang
Le répertoire ecrire/lang contient les différentes traductions de l’interface de SPIP. Ces traductions sont fournies grâce à 3 fichiers par langue (xx étant le code de langue) : 104 CHAPITRE 12. ECRIRE
• public_xx.php traduit des éléments des squelees publics,
• ecrire_xx.php traduit l’interface privée,
• spip_xx.php traduit… le reste ⁈ 105
Chapitre 13 prive
Le répertoire prive stocke tous les squelees qui concernent l’interface privée de SPIP ainsi que certaines CSS relatives à cet espace privé.
13.1 prive/editer
Le répertoire prive/editer contient les squelees qui appellent les formulaires d’édition de SPIP.
13.2 prive/formulaires
Le répertoire prive/formulaires contient les formulaires CVT d’édition des objets éditoriaux de SPIP.
13.3 prive/infos
Le répertoire prive/infos contient les squelees des cadres d’information des objets de l’espace privé, cadres contenant le numéro de l’objet, le statut, et quelques statistiques (nombre d’articles dans le cas d’une rubrique, nombre de visites pour un article…). 106 CHAPITRE 13. PRIVE 13.4 prive/javascript
Ce répertoire contient les scripts JavaScript dont jery utilisés dans l’espace privé et pour certains appelés par le pipeline jquery_plugins (p. 153) dans le site public également.
13.5 prive/modeles
Ce répertoire contient les modèles utilisables dans les textes pour les rédacteurs, tel que ,
13.6 prive/rss
Squelees générant les RSS du suivi éditorial dans l’espace privé, appelés via le fi- chier prive/rss.html avec une URL construite par la fonction bouton_spip_rss (déclarée dans ecrire/inc/presentation.php).
13.7 prive/stats
Squelees en rapport avec les statistiques…
13.8 prive/transmettre
Le répertoire prive/transmettre contient les squelees générant des données CSV, appelés depuis le squelee prive/transmettre.html.
13.9 prive/vignettes
Ce répertoire stocke les différentes icônes relatifs aux extensions de documents. La balise #LOGO_DOCUMENT retourne cee icône si aucune vignee de document n’est aribué. D’autres fonctions concernant ces vignees se trouvent dans ecrire/inc/documents.php. 13.10. PRIVE/IMAGES 107 13.10 prive/images
Ce répertoire contient les images et icônes utilisées dans l’espace privé et dans la procédure d’installation.
13.11 prive/contenu
Le répertoire prive/contenu contient les squelees servant à afficher le conte- nu d’un objet de SPIP, tel qu’un article (fichier article.html) dans l’interface privée.
13.12 prive/exec
Le répertoire prive/exec stocke les squelees SPIP permeant d’afficher des pages dans l’espace privé avec le paramètre ?exec=nom. Ce répertoire n’est pas présent dans le cœur de SPIP, mais des plugins peuvent l’utiliser. Une explication détaillée est donnée dans le chapitre sur la création de pages pour l’espace privé (p. 215). 108 CHAPITRE 13. PRIVE atrième partie
Étendre SPIP
109
111
SPIP a été conçu depuis longtemps pour être adaptable. Il existe de nombreuses solutions pour l’affiner selon ses propres besoins, ou pour créer de nouvelles fonctions. Cee partie explique différents moyens à la disposition des programmeurs pour étendre SPIP. 112 113
Chapitre 14
Généralités
Squelees, plugins, chemins d’accès, fonctions _dist()… Voici quelques expli- cations pour éclaircir tout cela !
14.1 Squelettes ou plugins ?
14.1.1 utiliser le dossier squelettes
Le dossier squelettes/ permet de stocker tous les fichiers nécessaires à la per- sonnalisation de votre site (squelees, images, fichiers Javascript ou CSS, librai- ries PHP…).
14.1.2 ou créer un plugin
Un plugin, stocké dans un répertoire plugins/nom_du_plugin/ permet égale- ment de stocker tout ce dont vous avez besoin pour votre site, exactement comme un dossier « squelees ». Il permet par contre quelques actions supplémentaires. Cela concerne principalement l’exécution possible de traitements à l’installation ou à la désinstallation du plugin. 114 CHAPITRE 14. GÉNÉRALITÉS
14.1.3 Alors, plugin ou simple dossier squelettes ?
D’une manière générale, on utilisera plutôt le dossier squelees pour installer tout ce qui est spécifique à un site. Dès qu’un code est générique et réutilisable, le proposer sous forme de plugin sera plus adapté.
14.2 Déclarer des options
Lorsqu’un visiteur du site demande à voir une page, qu’elle soit déjà en cache ou non, SPIP exécute un certain nombre d’actions, dont celles de charger des fichiers d’options. Ces options peuvent par exemple définir des constantes ou modifier des variables globales.
Ces options peuvent être créées dans le fichier config/mes_options.php ou de- puis un plugin en déclarant le nom du fichier dans plugin.xml tel que
1
2
3 // ’nom’ => ’chemin du squelette’
4 $squelettes = array(
5 ’2008’=>’squelettes/2008’,
6 ’2007’=>’squelettes/2007’,
7 );
8
9 // Si l’on demande un squelette particulier qui existe, on pose un cookie, sinon suppression du cookie
10 if (isset($_GET[’var_skel’])) {
11 if (isset($squelettes[$_GET[’var_skel’]]))
12 setcookie(’spip_skel’, $_COOKIE[’spip_skel’] = $_GET[’var_skel’], NULL, ’/’);
13 else
14 setcookie(’spip_skel’, $_COOKIE[’spip_skel’] = ’’, -24*3600, ’/’);
15 }
16 14.3. DÉCLARER DES FONCTIONS 115
17 // Si un squelette particulier est sauve, on le definit comme dossier squelettes
18 if (isset($_COOKIE[’spip_skel’]) AND isset($squelettes[$_COOKIE[’spip_skel’]]))
19 $GLOBALS[’dossier_squelettes’] = $squelettes[$_COOKIE[’spip_skel’]];
20
21 ?>
14.3 Déclarer des fonctions
Contrairement aux fichiers d’options, les fichiers de fonctions ne sont pas chargés systématiquement, mais seulement au calcul des squelees. Ils permeent par exemple de définir de nouveaux filtres utilisables dans les squelees. Ainsi, créer un fichier squelettes/mes_fonctions.php contenant le code ci-dessous, permet d’utiliser dans les squelees le filtre ”hello_world” (assez inutile !).
1
2 function filtre_hello_world($v, $add){
3 ^^Ireturn ”Titre:” . $v . ’ // Suivi de: ’ . $add;
4 }
5 ?>
1 [(#TITRE|hello_world{ce texte s’ajoute apr ¨ s})]
(affiche « Titre :titre de l’article // Suivi de : ce texte s’ajoute après ») Pour utiliser de tels fichiers avec les plugins, il suffit de déclarer le nom du fichier dans plugin.xml par exemple
14.3.1 fonctions spécifiques à des squelettes
Parfois, des filtres sont spécifiques à un seul fichier de squelee. Il n’est pas tou- jours souhaitable dans ce cas de charger systématiquement toutes les fonctions connues à chaque calcul de page. SPIP permet donc de créer des fonctions qui ne seront appelées qu’au calcul d’un squelee particulier. 116 CHAPITRE 14. GÉNÉRALITÉS
Il suffit de déclarer un fichier homonyme au squelee, dans le même répertoire, en le suffixant de _fonctions.php.
En reprenant l’exemple ci dessus, on pourrait tout à fait imaginer [(#TITRE|hello_world{ce texte s’ajoute après})] contenu dans un fichier squelettes/world.html et la fonction hello_world déclarée dans le fichier squelettes/world_fonctions.php
14.4 La notion de emin
SPIP s’appuie sur un certain nombre de fonctions et de squelees, contenus dans différents dossiers. Lorsqu’un script demande à ouvrir un fichier de SPIP pour charger une fonction ou lire un squelee, SPIP va regarder si le fichier existe dans un certain nombre de dossiers qu’il connaît. Dès qu’il le trouve, le fichier est alors utilisé. Les dossiers sont parcourus selon une certaine priorité, définie par une constante SPIP_PATH, et éventuellement complété par une globale $GLOBALS[’dossier_squelettes’] La lecture par défaut est la suivante :
• squelees
• plugin B dépendant du plugin A
• plugin A
• squelees-dist
• prive
• ecrire
• .
14.5 Surarger un fiier
Une des premières possibilités pour modifier un comportement de SPIP est de co- pier un des fichiers de SPIP dans un répertoire de plus haute priorité, par exemple dans un plugin, ou dans son dossier de squelees, en conservant la même arbo- rescence (sans prendre en compte le dossier ecrire/ néanmoins). 14.6. SURCHARGER UNE FONCTION _DIST 117
Ainsi, on pourrait imaginer modifier la façon dont SPIP gère le cache en copiant ecrire/public/cacher.php dans squelettes/public/cacher.php, puis en modifiant cee copie. C’est elle qui serait lue par défaut et en priorité. Cette façon de procéder est à utiliser en connaissance de cause. Effectivement, ce genre de modifications est très sensible aux évolutions de SPIP ; vous risque- riez d’avoir de grandes difficultés de mises à jour à chaque changement de version de SPIP.
14.6 Surarger une fonction _dist
De nombreuses déclarations de fonctions dans SPIP sont prévues pour n’être étendues qu’une seule fois. Ces fonctions possèdent l’extension « _dist » dans leur nom. Toutes les balises, boucles ou les critères sont déclarés de la sorte et peuvent donc être étendus de façon simple : en déclarant la même fonction, sans le suffixe « _dist » dans le nom.
Il existe dans le fichier ecrire/public/boucles.php la fonction boucle_ARTICLES_dist. Elle peut être surchargée en déclarant une fonction :
1 function boucle_ARTICLES($id_boucle, &$boucles) {
2 ...
3 }
14.6.1 Où surarger ces fonctions ?
Ces déclarations peuvent être faites dans un plugin ou dans le dossier squelees, dans un fichier d’options ou de fonctions. Tout ce qui concerne l’écriture de sque- lees (fonctions des balises, boucles, filtres ou critères) peuvent se surcharger dans un fichier de fonction tel que « mes_fonctions.php ». Les autres fonctions pouvant être appelées hors du calcul de squelee, il sera judicieux de les surchar- ger dans un fichier d’option tel que mes_options.php, chargé à chaque appel de page. 118 CHAPITRE 14. GÉNÉRALITÉS 15.1. INCLUDE_SPIP 119
Chapitre 15
Fonctions à connaître
SPIP dispose de nombreuses fonctions PHP fort utiles pour son fonctionnement. Certaines sont très utilisées et méritent quelques points d’explications.
Nom Description charger_fonction (p. 126) Trouver une fonction find_all_in_path (p. 121) Trouver une liste de fichiers find_in_path (p. 120) Trouver un fichier include_spip (p. 119) Inclure une librairie PHP recuperer_fond (p. 122) Retourner le résultat du calcul d’un squelee spip_log (p. 124) Ajouter une information dans les logs trouver_table (p. 127) Donne la description d’une table SQL. _request (p. 125) Récupérer une variable d’URL ou de formulaire
15.1 include_spip
La fonction include_spip() permet de charger une librairie PHP, un fichier. C’est l’équivalent du include_once() de PHP avec comme détail important le fait que le fichier demandé est recherché dans le path de SPIP, c’est à dire dans l’ensemble des dossiers connus, par ordre de priorité. La fonction prend 1 a 2 arguments et retourne l’adresse du fichier trouvé : 120 CHAPITRE 15. FONCTIONS À CONNAÎTRE
• nom ou adresse du fichier (sans l’extension .php)
• inclure (true par défaut) : inclure le fichier ou seulement retourner son adresse ?
1 include_spip(’fichier’);
2 include_spip(’dossier/fichier’);
3 $adresse = include_spip(’fichier’);
4 $adresse = include_spip(’fichier’, false); // inclusion non faite
15.1.1 Exemple
Charger le fichier de fonctions de mini présentations pour lancer la fonction minipres affichant une page d’erreur.
1 include_spip(’inc/minipres’);
2 echo minipres(’Pas de chance !’, ’Une erreur est survenue !’);
15.2 find_in_path
La fonction find_in_path() permet de récupérer l’adresse d’un fichier dans le path de SPIP. Elle prend 1 à 2 arguments :
• nom ou adresse du fichier (avec son extension)
• éventuellement dossier de stockage
1 $f = find_in_path(”dossiers/fichier.ext”);
2 $f = find_in_path(”fichier.ext”,”dossiers”); 15.3. FIND_ALL_IN_PATH 121
15.2.1 Exemple
Si un fichier inclusions/inc-special.html existe, récupérer le résultat de la compilation du squelee, sinon récupérer inclusions/inc-normal.html.
1 if (find_in_path(”inclusions/inc-special.html”)) {
2 ^^I$html = recuperer_fond(”inclusions/inc-special”);
3 } else {
4 ^^I$html = recuperer_fond(”inclusions/inc-normal”);
5 }
15.3 find_all_in_path
Cee fonction est capable de récupérer l’ensemble des fichiers répondant à un critère particulier de tous les répertoires connus des chemins de SPIP.
1 $liste_de_fichiers = find_all_in_path($dir, $pattern);
15.3.1 Exemple
SPIP utilise cee fonction pour récupérer l’ensemble des CSS que les plugins ajoutent à l’interface privée via les fichiers « prive/style_prive_plugin_prefix.html ». Pour cela SPIP récupère la liste de l’ensemble de ces fichiers en appelant :
1 $liste = find_all_in_path(’prive/’, ’/style_prive_plugin_’); 122 CHAPITRE 15. FONCTIONS À CONNAÎTRE 15.4 recuperer_fond
Autre fonction extrêmement importante de SPIP, recuperer_fond() permet de retourner le résultat du calcul d’un squelee donné. C’est en quelque sorte l’équi- valent de
• nom et adresse du fond (sans extension)
• contexte de compilation (tableau clé/valeur)
• tableau d’options
• nom du fichier de connexion à la base de données à utiliser
15.4.1 Utilisation simple
Le retour est le code généré par le résultat de la compilation :
1 $code = recuperer_fond($nom, $contexte);
15.4.2 Utilisation avancée
L’option raw définie à true permet, plutôt que de récupérer simplement le code généré, d’obtenir un tableau d’éléments résultants de la compilation, dont le code (clé texte). e contient donc ce tableau ? Le texte, l’adresse de la source du squelee (dans « source »), le nom du fichier de cache PHP généré par la compilation (dans « squelee »), un indicateur de présence de PHP dans le fichier de cache généré (dans « process_ins »), divers autres valeurs dont le contexte de compilation (la langue et la date s’ajoutent automatiquement puisqu’on ne les avait pas trans- mises). 15.4. RECUPERER_FOND 123
15.4.3 Exemple
Récupérer le contenu d’un fichier /inclure/inc-liste-articles.html en transmeant dans le contexte l’identifiant de la rubrique voulue :
1 $code = recuperer_fond(”inclure/inc-liste-articles”, array(
2 ^^I’id_rubrique’ => $id_rubrique,
3 ));
Option raw : _ Voici un petit test avec un squelee « ki.html » contenant simplement le texte ”hop”. Ici, le résultat est envoyé dans un fichier de log (tmp/test.log).
1 $infos = recuperer_fond(’ki’,array(),array(’raw’=>true));
2 spip_log($infos,’test’);
Résultat dans tmp/test.log :
1 array (
2 ’texte’ => ’hop
3 ’,
4 ’squelette’ => ’html_1595b873738eb5964ecdf1955e8da3d2’,
5 ’source’ => ’sites/tipi.magraine.net/squelettes/ki.html’,
6 ’process_ins’ => ’html’,
7 ’invalideurs’ =>
8 array (
9 ’cache’ => ’’,
10 ),
11 ’entetes’ =>
12 array (
13 ’X-Spip-Cache’ => 36000,
14 ),
15 ’duree’ => 0,
16 ’contexte’ =>
17 array (
18 ’lang’ => ’en’,
19 ’date’ => ’2009-01-05 14:10:03’,
20 ’date_redac’ => ’2009-01-05 14:10:03’, 124 CHAPITRE 15. FONCTIONS À CONNAÎTRE
21 ),
22 )
15.5 spip_log
Cee fonction permet de stocker des actions dans les fichiers de logs (générale- ment placés dans le répertoire tmp/log/).
Cee fonction prend 1 ou 2 arguments. Un seul, elle écrira dans le fichier spip.log. Deux, elle écrira dans un fichier séparé et aussi dans spip.log.
1
2 spip_log($tableau);
3 spip_log($tableau, ’second_fichier’);
4 spip_log(”ajout de $champ dans $table”,”mon_plugin”);
5 ?>
Lorsqu’un tableau est transmis à la fonction de log, SPIP écrira le résultat d’un print_r() dans le fichier de log. Pour chaque fichier demandé, ici spip (par défaut) et second_fichier, SPIP créera ou ajoutera le contenu du premier ar- gument, mais pas n’importe où. Si le script est dans l’interface privée, il écrira dans « prive_spip.log » ou « prive_second_fichier.log », sinon dans « spip.log » ou « second_fichier.log ».
Le fichier de configuration ecrire/inc_version.php définit la taille maximale des fichiers de log. Lorsqu’un fichier dépasse la taille souhaitée, il est copié sous un autre nom, par exemple prive_spip.log.n (n s’incrémentant). Ce nombre de fichiers copiés est aussi réglable. Il est aussi possible de désactiver les logs en meant une de ces valeurs à zéro dans mes_options.php.
1 $GLOBALS[’nombre_de_logs’] = 4; // 4 fichiers au plus
2 $GLOBALS[’taille_des_logs’] = 100; // de 100ko au plus
Une constante _MAX_LOG (valant 100 par défaut) indique le nombre d’entrées que chaque appel d’une page peut écrire. Ainsi, après 100 appels de spip_log() par un même script, la fonction ne log plus. 15.6. _REQUEST 125 15.6 _request
La fonction _request() permet de récupérer des variables envoyées par l’inter- naute, soit par l’URL, soit par un formulaire posté.
1 $nom = _request(’nom’);
15.6.1 Principes de sécurité
Ces fonctions ne doivent pas être placées n’importe où dans les fichiers de SPIP, ceci afin de connaître précisément les lieux possibles de tentatives de piratage. Les éléments issus de saisies utilisateurs ne devraient être récupérés que dans
• les fichiers d’actions (dans le répertoire action/),
• les fichiers d’affichage privé (dans le répertoire exec/),
• pour certaines très rares balises dynamiques (dans le répertoire balise/),
• ou dans les fichiers de formulaires (dans le répertoire formulaires/).
Il faut en règle générale en plus, vérifier que le type reçu est bien au format at- tendu (pour éviter tout risque de hack, bien que SPIP effectue déjà un premier neoyage de ce qui est reçu), par exemple, si vous aendez un nombre, il faut ap- pliquer la fonction intval() (qui transformera tout texte en valeur numérique) :
1 if ($identifiant = _request(’identifiant’)){
2 ^^I$identifiant = intval($identifiant);
3 }
15.6.2 Récupérer dans un tableau
Si vous souhaitez récupérer uniquement parmi certaines valeurs présentes dans un tableau, vous pouvez passer ce tableau en second paramètre : 126 CHAPITRE 15. FONCTIONS À CONNAÎTRE
1 // recupere s’il existe $tableau[’nom’]
2 $nom = _request(’nom’, $tableau);
15.6.3 Exemple
Récupérer uniquement parmi les valeurs transmises dans l’URL :
1 $nom = _request(’nom’, $_GET);
15.7 arger_fonction
Cee fonction charger_fonction() permet de récupérer le nom d’une fonction surchargeable de SPIP. Lorsqu’une fonction interne suffixée de _dist() est sur- chargée (en la recréant sans ce suffixe), ou lorsqu’on surcharge l’ensemble d’un fichier contenant une fonction de la sorte, il faut pouvoir récupérer la bonne fonction au moment de son exécution.
C’est cela que fait charger_fonction(). Elle retourne le nom de la fonction à exécuter.
1 $ma_fonction = charger_fonction(’ma_fonction’,’repertoire’);
2 $ma_fonction();
15.7.1 Principe de reere
La fonction se comporte comme suit :
• elle retourne si la fonction est déjà déclarée repertoire_ma_fonction,
• sinon repertoire_ma_fonction_dist,
• sinon tente de charger un fichier repertoire/ma_fonction.php puis 15.8. TROUVER_TABLE 127
• retourne repertoire_ma_fonction si existe,
• sinon repertoire_ma_fonction_dist,
• sinon renvoie false.
15.7.2 Exemple
Envoyer un mail :
1 $envoyer_mail = charger_fonction(’envoyer_mail’, ’inc’);
2 $envoyer_mail($email, $sujet, $corps);
15.8 trouver_table
La fonction trouver_table() (base_trouver_table_dist) est déclarée dans ecrire/base/trouver_table.php et permet d’obtenir une description d’une table SQL. Elle permet de récupérer la liste des colonnes, des clés, des jointures dé- clarées, et d’autres informations. En tant que fonction surchargeable, elle s’utilise avec charger_fonction (p. 126):
1 $trouver_table = charger_fonction(’trouver_table’, ’base’);
2 $desc = $trouver_table($table, $serveur);
Ses paramètres sont :
1. $table : le nom de la table (’spip_articles’ ou ’articles’)
2. $serveur : optionnel, le nom de la connexion SQL utilisée, qui est par défaut celle de l’installation de SPIP. Le tableau $desc retourné est de cee forme : 128 CHAPITRE 15. FONCTIONS À CONNAÎTRE
1 array(
2 ^^I’field’ => array(’colonne’ => ’description’),
3 ^^I’key’ => array(
4 ^^I^^I’PRIMARY KEY’ => ’colonne’,
5 ^^I^^I’KEY nom’ => ’colonne’ // ou ’colonne1, colonne2’
6 ^^I),
7 ^^I’join’ => array(’colonne’ => ’colonne’),
8 ^^I’table’ => ’spip_tables’
9 ^^I’id_table’ => $table,
10 ^^I’connexion’ => ’nom_connexion’,
11 ^^I’titre’ => ’colonne_titre AS titre, colonne_langue AS lang’
12 );
• La clé field est un tableau associatif listant toutes les colonnes de la table et donnant leur description SQL,
• key est un autre tableau listant les clés primaires et secondaires,
• join liste les colonnes de jointures possibles, si déclarés dans la description des tables principales ou auxiliaires
• table est le véritable nom de la table (hors préfixe : si le préfixe des tables est différent de « spip », c’est « spip_tables » qui sera tout de même re- tourné),
• id_table est le paramètre $table donné,
• connexion est le nom du fichier de connexion, si différent de celui d’ins- tallation,
• titre est une déclaration SQL de SELECT indiquant où est la colonne titre ou où est la colonne langue (sert entre autre pour calculer les URLs) ; exemples : « titre, lang », « nom AS titre, ’’ AS lang » Cee fonction met en cache (p. 258) le résultat de l’analyse afin d’éviter des accès intempestifs au serveur SQL. Pour forcer un recalcul de ce cache, il faut appeler la fonction avec une chaine vide :
1 $trouver_table = charger_fonction(’trouver_table’, ’base’);
2 $desc = $trouver_table(’’);
Note : Lorsqu’une table est demandée sans préfixe « spip_ », c’est le nom de la table avec le préfixe donné pour le site qui sera retourné (pour peu que la 15.8. TROUVER_TABLE 129
table soit déclarée à SPIP). Demander une table « spip_tables » cherchera l’existence véritable de cee table (le préfixe n’est pas remplacé par celui utilisé pour le site). Dans l’avenir, une option sera probablement ajoutée à la fonction trouver_table(), comme pour sql_showtable (p. 342) afin de pouvoir modifier automatiquement le préfixe.
15.8.1 Exemple
La fonction creer_champs_extras() du plugin « Champs Extras » permet de créer les colonnes SQL décrites par les instances d’objets « ChampExtra » trans- mises ($c->table est le nom de la table SQL, $c->champ celui de la colonne). La fonction renvoie false si une colonne n’a pas été créée :
1 function creer_champs_extras($champs) {
2 ^^I// la fonction met a jour les tables concernées avec maj_tables()
3 ^^I// [...]
4 ^^I// Elle teste ensuite si les nouveaux champs sont bien crees :
5 ^^I// pour chaque champ a creer, on verifie qu’il existe bien maintenant !
6 ^^I$trouver_table = charger_fonction(’trouver_table’,’base’);
7 ^^I$trouver_table(’’); // recreer la description des tables.
8 ^^I$retour = true;
9 ^^Iforeach ($champs as $c){
10 ^^I^^Iif ($table = table_objet_sql($c->table)) {
11 ^^I^^I^^I$desc = $trouver_table($table);
12 ^^I^^I^^Iif (!isset($desc[’field’][$c->champ])) {
13 ^^I^^I^^I^^Iextras_log(”Le champ extra ’” . $c->champ . ”’ sur $table n’a pas ete cree :(”, true);
14 ^^I^^I^^I^^I$retour = false;
15 ^^I^^I^^I}
16 ^^I^^I} else {
17 ^^I^^I^^I$retour = false;
18 ^^I^^I}
19 ^^I}
20 ^^Ireturn $retour;
21 } 130 CHAPITRE 15. FONCTIONS À CONNAÎTRE 131
Chapitre 16
Les pipelines
À certains endroits du code sont définis des « pipelines ». Les utiliser est une des meilleures façons de modifier ou d’adapter des comportements de SPIP.
16.1 ’est-ce qu’un pipeline ?
Un pipeline (p. 377) permet de faire transiter un code entre plusieurs intermé- diaires (des fonctions) pour le compléter ou le modifier.
16.1.1 Déclaration dans un plugin
Chaque plugin peut utiliser un pipeline existant. Pour cela, il déclare son utilisa- tion dans le fichier plugin.xml de la sorte :
1
2
3
4
• Nom : indique le nom du pipeline à utiliser,
• Inclure : indique le nom du fichier qui contient la fonction à exécuter au moment de l’appel du pipeline (prefixPlugin_nomPipeline()). 132 CHAPITRE 16. LES PIPELINES
16.1.2 Déclaration hors plugin
Une utilisation d’un pipeline en dehors du cadre d’un plugin reste possible. Il faut alors déclarer son utilisation directement dans le fichier config/mes_options.php :
1 $GLOBALS[’spip_pipeline’][’nom_du_pipeline’] .= ”|nom_de_la_fonction”;
2 // Exemple d’ajout dans le pipeline ”insert_head” :
3 $GLOBALS[’spip_pipeline’][’insert_head’] .= ”|nom_de_la_fonction”;
4
5 function nom_de_la_fonction($flux) {
6 ^^Ireturn $flux .= ”Ce texte sera ajoute”;
7 }
La fonction appelée doit être connue au moment de l’appel du pipeline, le plus simple étant de la déclarer comme ici pour la fonction nom_de_la_fonction dans le fichier d’option.
16.1.3 En savoir plus !
À noter que SPIP utilise un cache des pipelines utilisés (p. 259) et que toute nou- velle déclaration nécessite de recalculer ce cache. Cela se fait en visitant la page « Gestion des plugins » dans l’espace privé (?exec=admin_plugin).
16.2 els sont les pipelines existants ?
La liste des pipelines intégrés à SPIP (mais des plugins peuvent en créer de nou- veaux) est visible dans le fichier ecrire/inc_version.php. Plusieurs types de pipe- lines existent, certains concernent les traitements typographiques, d’autres les enregistrements en base de données, d’autres l’affichage des pages privées ou publiques… 16.3. DÉCLARER UN NOUVEAU PIPELINE 133 16.3 Déclarer un nouveau pipeline
Cela se passe en deux temps. Il faut tout d’abord déclarer l’existence du pipeline dans un fichier d’option $GLOBALS[’spip_pipeline’][’nouveau_pipe’] = ’’ Ensuite, il faut l’appeler quelque part, soit dans un squelee soit dans un fichier PHP. La balise #PIPELINE ou la fonction PHP pipeline() utilisent les mêmes arguments.
• Squelees : #PIPELINE{nouveau_pipe,contenu au demarrage}
• Php : $data = pipeline(’nouveau_pipe’,”contenu au demarrage”);. Dans les deux écritures, un premier texte « contenu au demarrage » est envoyé dans le pipeline. Tous les plugins ayant déclaré l’utilisation de ce pipeline vont recevoir la chaîne et pouvoir la compléter ou modifier. Après le dernier, le résultat est renvoyé.
16.4 Des pipelines argumentés
Il est souvent indispensable de passer des arguments issus du contexte, en plus des données renvoyées par le pipeline. Cela est permis en transmeant un ta- bleau d’au moins deux clés avec une clé nommée ”data”. À la fin du chaînage des pipelines, seule la valeur de ’data’ est renvoyée.
1 $data = pipeline(’nouveau_pipe’,array(
2 ^^I’args’=>array(
3 ^^I^^I’id_article’=>$id_article
4 ^^I),
5 ^^I’data’=>”contenu au demarrage”
6 ));
1 [(#PIPELINE{nouveau_pipe,
2 ^^I[(#ARRAY{
3 ^^I^^Iargs,[(#ARRAY{id_article,#ID_ARTICLE})],
4 ^^I^^Idata,contenu au demarrage
5 ^^I})]})] 134 CHAPITRE 16. LES PIPELINES 135
Chapitre 17
Liste des pipelines
Cee partie décrit l’utilisation de certains pipelines de SPIP.
Nom Description accueil_encours (p. 162) Ajouter du contenu au centre de la page d’accueil. accueil_gadget (p. 163) Ajouter des raccourcis en haut du contenu de la page d’accueil. accueil_informations (p. 164) Informer sur les statistiques des ob- jets éditoriaux sur la page d’accueil. affichage_entetes_final (p. 187) Modifier les entêtes des pages en- voyées affichage_final (p. 165) Effectue des traitements juste avant l’envoi des pages publiques. afficher_config_objet (p. 161) Ajouter des éléments dans un cadre de configuration des objets édito- riaux afficher_contenu_objet (p. 190) Modifier ou compléter la vue d’un objet dans l’interface privée. afficher_fiche_objet (p. 159) Ajouter du contenu dans la vue des objets éditoriaux afficher_nombre_objets_associes_a (p. 203) Compléter les informations de nombre d’éléments liés à des objets dans l’interface privée. affiche_droite (p. 166) Ajouter du contenu dans la colonne « droite » de l’espace privé. 136 CHAPITRE 17. LISTE DES PIPELINES
Nom Description affiche_enfants (p. 169) Modifier ou compléter le contenu des listes présentant les enfants d’un ob- jet dans l’espace privé affiche_gauche (p. 167) Ajouter du contenu dans la colonne « gauche » de l’espace privé. affiche_hierarchie (p. 168) Modifier le code HTML du fil d’ariane de l’espace privé. affiche_milieu (p. 149) Ajouter du contenu au centre de la page sur les pages privées. ajouter_boutons (p. 171) Ajouter des boutons dans le menu de l’espace privé. ajouter_onglets (p. 173) Ajouter des onglets dans les pages de l’espace privé. alertes_auteur (p. 198) Ajouter des alertes à l’auteur connec- té dans l’espace privé. autoriser (p. 170) Charger des fonctions d’autorisa- tions. body_prive (p. 162) Insérer du contenu après
dans l’espace privé. boite_infos (p. 142) Afficher des informations sur les ob- jets dans les boîtes infos de l’espace privé. compter_contributions_auteur (p. 193) Compter les contributions d’un au- teur declarer_tables_auxiliaires (p. 147) déclarer des tables SQL « auxi- liaires » declarer_tables_interfaces (p. 177) Déclarer des informations tierces sur les tables SQL (alias, traitements, jointures, …) declarer_tables_objets_surnoms (p. 150) Indiquer la relation entre le type d’objet et sa correspondance SQL. declarer_tables_principales (p. 145) Déclarer des tables SQL « princi- pales » declarer_url_objets (p. 183) Permere des URL standard sur un nouvel objet éditorial definir_session (p. 185) Définir les paramètres distinguant les caches par visiteur delete_statistiques (p. 191) Trigger au moment d’un effacement des tables de statistiques. 137Nom Description delete_tables (p. 191) Trigger au moment d’un effacement de la base de donnée. editer_contenu_objet (p. 156) Modifier le contenu HTML des for- mulaires. formulaire_charger (p. 155) Modifier le tableau retourné par la fonction charger d’un formulaire CVT. formulaire_traiter (p. 196) Modifier le tableau retourné par la fonction traiter d’un formulaire CVT ou effectuer des traitements supplémentaires. formulaire_verifier (p. 194) Modifier le tableau retourné par la fonction verifier d’un formulaire CVT. header_prive (p. 176) Ajouter des contenus dans le
privé. insert_head (p. 141) Ajouter des contenus dans le public. insert_head_css (p. 196) Ajouter des CSS dans l’espace public jquery_plugins (p. 153) Ajouter des scripts JavaScript (espace public et privé). libelle_association_mots (p. 148) Compléter la liste des noms d’objets que l’on peut lier à un groupe de mots. lister_tables_noerase (p. 190) Liste des tables à ne pas vider avant d’une restauration. lister_tables_noexport (p. 189) Liste des tables SQL à ne pas sauve- garder lister_tables_noimport (p. 190) Liste des tables SQL à ne pas impor- ter. objet_compte_enfants (p. 201) Compter les enfants d’un objet. optimiser_base_disparus (p. 160) Neoyer des éléments orphelins dans la base de données post_insertion (p. 154) Effectuer une action après l’insertion d’un nouvel élément en base. post_typo (p. 200) Modifier le texte après les traite- ments typographiques pre_boucle (p. 144) Modifier les requêtes SQL servant à générer les boucles. 138 CHAPITRE 17. LISTE DES PIPELINESNom Description pre_insertion (p. 158) Ajouter des contenus par défaut au moment d’une insertion dans la base de données pre_liens (p. 138) Traiter les raccourcis typographiques relatifs aux liens pre_typo (p. 199) Modifier le texte avant les traite- ments typographiques rechercher_liste_des_champs (p. 140) Définir des champs et des pondé- rations pour les recherches sur une table. rechercher_liste_des_jointures (p. 140) Définir des jointures pour les re- cherches sur une table. recuperer_fond (p. 175) Modifie le résultat de compilation d’un squelee rubrique_encours (p. 157) Ajouter du contenu dans l’espace « Proposés à publication » des ru- briques styliser (p. 151) Modifier la recherche des squelees utilisés pour générer une page. taches_generales_cron (p. 192) Assigner des tâches périodiques trig_supprimer_objets_lies (p. 194) Supprimer des liaisons d’objets au moment de la suppression d’un objet … et les autres (p. 204) Ceux qui restent à documenter
17.1 pre_liens
Le pipeline « pre_liens » permet de traiter les raccourcis typographiques relatifs aux liens tel que [titre->url]. Il est appelé par la fonction expanser_liens(), elle-même appelée par la fonction propre().
1 $texte = pipeline(’pre_liens’, $texte);
SPIP se sert lui-même de ce point d’entrée pour effectuer des traitements sur le texte reçu en intégrant 3 fonctions dans la définition du pipeline dans le fichier ecrire/inc_version.php, définies dans le fichier ecrire/inc/lien.php :
• traiter_raccourci_liens génère automatiquement des liens si un texte ressemble à une URL, 17.1. PRE_LIENS 139
• traiter_raccourci_glossaire gère les raccourcis [?titre] pointant vers un glossaire (p. 371).
• traiter_raccourci_ancre s’occupe des raccourcis [<-nom de l’ancre] créant une ancre nommée
17.1.1 Exemple
Le plugin « documentation » (qui gère cee documentation), utilise ce pipeline pour ajouter automatiquement un aribut title sur les raccourcis de liens in- ternes comme [->art30], le transformant en [|art30->art30] (ce pis-aller sert à afficher le numéro de la page relative au lien lorsque l’on exporte le conte- nu de la documentation au format PDF)
1 function documentation_pre_liens($texte){
2 ^^I// uniquement dans le public
3 ^^Iif (test_espace_prive()) return $texte;
4 ^^I$regs = $match = array();
5 ^^I// pour chaque lien
6 ^^Iif (preg_match_all(_RACCOURCI_LIEN, $texte, $regs, PREG_SET_ORDER)) {
7 ^^I^^Iforeach ($regs as $reg) {
8 ^^I^^I^^I// si le lien est de type raccourcis ”art40”
9 ^^I^^I^^Iif (preg_match(_RACCOURCI_URL, $reg[4], $match)) {
10 ^^I^^I^^I^^I$title = ’|’ . $match[1] . $match[2];
11 ^^I^^I^^I^^I// s’il n’y a pas deja ce title
12 ^^I^^I^^I^^Iif (false === strpos($reg[0], $title)) {
13 ^^I^^I^^I^^I^^I$lien = substr_replace($reg[0], $title, strpos($reg[0], ’->’), 0);
14 ^^I^^I^^I^^I^^I$texte = str_replace($reg[0], $lien, $texte);
15 ^^I^^I^^I^^I}
16 ^^I^^I^^I}
17 ^^I^^I}
18 ^^I}
19 ^^Ireturn $texte;
20 } 140 CHAPITRE 17. LISTE DES PIPELINES 17.2 reerer_liste_des_amps
Ce pipeline permet de gérer les champs pris en compte par le moteur de recherche de SPIP pour une table donnée. Ce pipeline reçoit un tableau de noms d’objet SPIP (article, rubrique…) contenant les noms des champs à prendre en compte pour la recherche (titre, texte…) affectés d’un coefficient de pondération du résultat : plus le coefficient est élevé, plus la recherche aribue des points si la valeur cherchée est présente dans le champ.
17.2.1 Exemple
1 function prefixPlugin_rechercher_liste_des_champs($tables){
2 ^^I// ajouter un champ ville sur les articles
3 ^^I$tables[’article’][’ville’] = 3;
4 ^^I// supprimer un champ de la recherche
5 ^^Iunset($tables[’rubrique’][’descriptif’]);
6 ^^I// retourner le tableau
7 ^^Ireturn $tables;
8 }
17.3 reerer_liste_des_jointures
Ce pipeline utilisé dans ecrire/inc/rechercher.php permet de déclarer des recherches à effectuer sur d’autres tables que la table où la recherche est demandée, pour re- tourner des résultats en fonction de données extérieures à la table. Grâce à cela, une recherche d’un nom d’auteur sur une boucle ARTICLES retourne les articles associés au nom de l’auteur (via la table AUTEURS). Ce pipeline reçoit un tableau de tables contenant un tableau de couples table, champ, pondération (comme le pipeline « rechercher_liste_des_champs »). 17.4. INSERT_HEAD 141
17.3.1 Exemple
Voici un exemple de modifications pour la table article.
1 function prefixePlugin_rechercher_liste_des_jointures($tables){
2 ^^I// rechercher en plus dans la BIO de l’auteur si on cherche dans un article (oui c’est aberrant !)
3 ^^I$tables[’article’][’auteur’][’bio’] = 2;
4 ^^I// rechercher aussi dans le texte des mots cles
5 ^^I$tables[’article’][’mot’][’texte’] = 2;
6 ^^I// ne pas chercher dans les documents
7 ^^Iunset($tables[’article’][’document’]);
8 ^^I// retourner l’ensemble
9 ^^Ireturn $tables;
10 }
17.4 insert_head
Le pipeline insert_head permet d’ajouter des contenus dans la partie
d’une page HTML :• au moment de l’appel à #INSERT_HEAD si la balise est définie,
• sinon juste avant la fin du header (avant ) si la fonction f_insert_head est définie dans le pipeline affichage_final (p. 165), par exemple avec ceci dans mes_options.php :
1 $GLOBALS[’spip_pipeline’][’affichage_final’] .= ’|f_insert_head’;
Le pipeline reçoit le contenu à ajouter et retourne donc un contenu :
1 function prefixPlugin_insert_head($flux){
2 ^^I$flux .= ”\n”;
3 ^^Ireturn $flux;
4 } 142 CHAPITRE 17. LISTE DES PIPELINES
17.4.1 Exemple
Ajouter un appel à une fonction jery, ici pour afficher une barre d’outil sur les balises textarea des formulaires de Crayons (avec le plugin Porte Plume) :
1 function documentation_insert_head($flux){
2 ^^I$flux .= << 3 4 16 17 EOF; 18 ^^Ireturn $flux; 19 } La fonction JavaScript onAjaxLoad permet de rappeler la fonction donnée en paramètre lors d’un rechargement AJAX d’un élément de la page. 17.5 boite_infos Ce pipeline permet de gérer les informations affichées dans l’espace privé dans le cadre d’information des objets SPIP. C’est dans ce cadre par exemple qu’est affiché le numéro d’un article, ainsi que les liens pour changer son statut. Il reçoit un tableau en paramètre. 17.5. BOITE_INFOS 143 • data : contient ce qui sera ensuite affiché sur la page, • args contient un tableau avec : – type : le type d’objet (article, rubrique…) – id : l’identifiant (8, 12…) – row : tableau contenant l’ensemble des champs SQL de l’objet et leurs valeurs. 17.5.1 Exemple Le plugin « Prévisualisation pour les articles en cours de rédaction » (previ- su_redac) utilise ce pipeline pour ajouter le bouton « previsualiser » lorsqu’un article est en cours de rédaction (ce lien n’apparaît normalement que lorsque l’article a été proposé à publication) : 1 function previsu_redac_boite_infos(&$flux){ 2 ^^Iif ($flux[’args’][’type’]==’article’ 3 ^^I AND $id_article=intval($flux[’args’][’id’]) 4 ^^I AND $statut = $flux[’args’][’row’][’statut’] 5 ^^I AND $statut == ’prepa’ 6 ^^I AND autoriser(’previsualiser’)){ 7 ^^I^^I$message = _T(’previsualiser’); 8 ^^I^^I$h = generer_url_action(’redirect’, ”type=article&id=$id_article&var_mode=preview”); 9 ^^I^^I$previsu = 10 ^^I^^Iicone_horizontale($message, $h, ”racine-24.gif”, ”rien.gif”,false); 11 ^^I^^Iif ($p = strpos($flux[’data’],’
12 ^^I^^I^^Iwhile($q = strpos($flux[’data’],’
13 ^^I^^I^^I$flux[’data’] = substr($flux[’data’],0,$p+5) . $previsu . substr($flux[’data’], $p+5);
14 ^^I^^I}
15 ^^I^^Ielse
16 ^^I^^I^^I$flux[’data’].= $previsu;
17 ^^I}
18 ^^Ireturn $flux;
19 } 144 CHAPITRE 17. LISTE DES PIPELINES 17.6 pre_boucle
Le pipeline pre_boucle permet de modifier les requêtes SQL servant à générer les boucles. Il agit après la prise en compte des critères (fonctions critere_NOM()) par le compilateur et avant l’appel des fonctions boucle_NOM(). Ce pipeline est appelé à la création de chaque boucle au moment de la compila- tion. Il reçoit un objet Boucle en paramètre, contenant les données issues de la compilation concernant la boucle parcourue. Il est ainsi possible d’agir sur la boucle en fonction des critères qui lui sont pas- sés, par exemple en modifiant les paramètres de sélections ou la condition where d’une boucle.
17.6.1 Exemple
Le plugin « mots techniques » ajoute un champ technique sur les groupes de mots de SPIP. Lorsqu’aucun critère {technique} n’est ajouté sur la boucle GROUPES_MOTS, la boucle est alors filtrée automatiquement, affichant unique- ment les groupes ayant un champ technique vide. Ce fonctionnement pourrait aussi être réalisé en créant une fonction boucle_GROUPES_MOTS().
1 function mots_techniques_pre_boucle($boucle){
2 ^^Iif ($boucle->type_requete == ’groupes_mots’) {
3 ^^I^^I$id_table = $boucle->id_table;
4 ^^I^^I$mtechnique = $id_table .’.technique’;
5 ^^I^^I// Restreindre aux mots cles non techniques
6 ^^I^^Iif (!isset($boucle->modificateur[’criteres’][’technique’]) &&
7 ^^I^^I^^I!isset($boucle->modificateur[’tout’])) {
8 ^^I^^I^^I^^I$boucle->where[]= array(”’=’”, ”’$mtechnique’”, ”’\”\”’”);
9 ^^I^^I}
10 ^^I}
11 ^^Ireturn $boucle;
12 }
Le tableau $boucle->where[] reçoit comme valeurs des tableaux. Ces tableaux ont 3 entrées : l’opérateur, le champ, la valeur. Ici, on ajoute $mtechnique=’’ par : 17.7. DECLARER_TABLES_PRINCIPALES 145
1 $boucle->where[]= array(”’=’”, ”’$mtechnique’”, ”’\”\”’”);
17.7 declarer_tables_principales
Ce pipeline permet de déclarer des tables ou des champs de tables supplémen- taires à SPIP, en indiquant le type SQL de chaque champ, les clés primaires, les clés d’index, parfois des clés de jointures. Ce pipeline concerne les tables dites « principales » qui contiennent du contenu éditorial, à comparer aux tables dites « auxiliaires » qui contiennent plutôt des tables de liaisons entre les tables principales. Ces déclarations servent à SPIP pour :
• gérer l’affichage des boucles (mais ce n’est pas indispensable car SPIP sait récupérer les descriptions d’une table même si elle n’est pas déclarée),
• créer les tables (ou les champs manquants) à l’installation de SPIP ou d’un plugin,
• prendre en compte ces tables et ces champs dans les sauvegardes et restau- rations faites par le gestionnaire de sauvegarde de SPIP (les dump). La fonction prend en paramètre la liste des tables déjà déclarées et doit re- tourner ce tableau. Ce tableau liste des tables avec pour chacune un tableau de 2 à 3 clés (join est optionnel) :
1 $tables_principales[’spip_nom’] = array(
2 ^^I’field’ => array(’champ’=>’code sql de creation’),
3 ^^I’key’ => array(’type’ => ’nom du/des champs’),
4 ^^I’join’ => array(’champ’=>’champ de liaison’)
5 );
SPIP fait appel à ce pipeline lors de la déclaration des tables utilisées, dans le fichier ecrire/base/serial.php. 146 CHAPITRE 17. LISTE DES PIPELINES
17.7.1 Exemple
Le plugin « Agenda » déclare une table « spip_evenements » avec de nom- breux champs. Il déclare la clé primaire (id_evenement), 3 index (date_debut, date_fin et id_article), ainsi que deux clés potentielles pour les jointures : id_evenement et id_article (je crois que l’ordre est important).
Ce plugin déclare aussi un champ ”agenda” dans la table spip_rubriques.
1 function agenda_declarer_tables_principales($tables_principales){
2 ^^I//-- Table EVENEMENTS ------
3 ^^I$evenements = array(
4 ^^I^^I”id_evenement”^^I=> ”bigint(21) NOT NULL”,
5 ^^I^^I”id_article”^^I=> ”bigint(21) DEFAULT ’0’ NOT NULL”,
6 ^^I^^I”date_debut”^^I=> ”datetime DEFAULT ’0000-00-00 00:00:00’ NOT NULL”,
7 ^^I^^I”date_fin”^^I=> ”datetime DEFAULT ’0000-00-00 00:00:00’ NOT NULL”,
8 ^^I^^I”titre”^^I=> ”text NOT NULL”,
9 ^^I^^I”descriptif”^^I=> ”text NOT NULL”,
10 ^^I^^I”lieu”^^I=> ”text NOT NULL”,
11 ^^I^^I”adresse”^^I=> ”text NOT NULL”,
12 ^^I^^I”inscription” => ”tinyint(1) DEFAULT 0 NOT NULL”,
13 ^^I^^I”places” => ”int(11) DEFAULT 0 NOT NULL”,
14 ^^I^^I”horaire” => ”varchar(3) DEFAULT ’oui’ NOT NULL”,
15 ^^I^^I”id_evenement_source”^^I=> ”bigint(21) NOT NULL”,
16 ^^I^^I”maj”^^I=> ”TIMESTAMP”
17 ^^I^^I);
18
19 ^^I$evenements_key = array(
20 ^^I^^I”PRIMARY KEY”^^I=> ”id_evenement”,
21 ^^I^^I”KEY date_debut”^^I=> ”date_debut”,
22 ^^I^^I”KEY date_fin”^^I=> ”date_fin”,
23 ^^I^^I”KEY id_article”^^I=> ”id_article”
24 ^^I^^I);
25
26 ^^I$tables_principales[’spip_evenements’] = array(
27 ^^I^^I’field’ => &$evenements,
28 ^^I^^I’key’ => &$evenements_key,
29 ^^I^^I’join’=>array(
30 ^^I^^I^^I’id_evenement’=>’id_evenement’, 17.8. DECLARER_TABLES_AUXILIAIRES 147
31 ^^I^^I^^I’id_article’=>’id_article’
32 ^^I^^I));
33
34 ^^I$tables_principales[’spip_rubriques’][’field’][’agenda’] = ’tinyint(1) DEFAULT 0 NOT NULL’;
35
36 ^^Ireturn $tables_principales;
37 }
17.8 declarer_tables_auxiliaires
Ce pipeline sert à déclarer des tables « auxiliaires », c’est à dire qui ne servent essentiellement qu’à réaliser des liaisons avec des tables principales. Comme le pipeline declarer_tables_principales (p. 145), il reçoit la liste des tables, se composant du même tableau.
17.8.1 Exemple
Le plugin « SPIP Bisous » qui permet qu’un auteur (membre inscrit sur le site) envoie un bisou à un autre auteur (l’équivalent d’un poke sur certains réseaux sociaux) déclare une table spip_bisous liant 2 auteurs avec la date du bisou, avec le code ci-dessous. On remarquera la clé primaire composée de 2 champs.
1 function bisous_declarer_tables_auxiliaires($tables_auxiliaires){
2
3 ^^I$spip_bisous = array(
4 ^^I^^I’id_donneur’ => ’bigint(21) DEFAULT ”0” NOT NULL’,
5 ^^I^^I’id_receveur’ => ’bigint(21) DEFAULT ”0” NOT NULL’,
6 ^^I^^I’date’ => ’datetime DEFAULT ”0000-00-00 00:00:00” NOT NULL’
7 ^^I);
8
9 ^^I$spip_bisous_cles = array(
10 ^^I^^I’PRIMARY KEY’ => ’id_donneur, id_receveur’
11 ^^I); 148 CHAPITRE 17. LISTE DES PIPELINES
12
13 ^^I$tables_auxiliaires[’spip_bisous’] = array(
14 ^^I^^I’field’ => &$spip_bisous,
15 ^^I^^I’key’ => &$spip_bisous_cles
16 ^^I);
17
18 ^^Ireturn $tables_auxiliaires;
19 }
17.9 libelle_association_mots
Le pipeline libelle_association_mots est appelé dans ecrire/exec/mots_tous.php pour afficher le texte des éléments que l’on peut lier à un groupe de mots donné. À chaque objet est associé un nom de chaine de langue :
1 $libelles = array(
2 ^^I’articles’=>’info_articles_2’,
3 ^^I’breves’=>’info_breves_02’,
4 ^^I’rubriques’=>’info_rubriques’,
5 ^^I’syndic’=>’icone_sites_references’
6 );
7 $libelles = pipeline(’libelle_association_mots’, $libelles);
Est transmis au pipeline, donc, un tableau ayant pour clé les noms d’objets (au pluriel), et en valeur un nom de chaine de langue.
17.9.1 Exemple
Le plugin « Mots objets » permeant d’ajouter des mots sur les auteurs et docu- ments, transmets les chaines de langue correspondantes comme ceci :
1 function mots_objets_libelle_association_mots($flux){
2 17.10. AFFICHE_MILIEU 149
3 ^^I$flux[’auteurs’] = ’mots_objets:objet_auteurs’;
4
5 ^^I$flux[’documents’] = ’gestdoc:objet_documents’;
6 // plugin mediatheque
7 ^^Ireturn $flux;
8
9 }
17.10 affie_milieu
Ce pipeline permet d’ajouter du contenu sur les pages exec/ de SPIP, après le contenu prévu au centre de la page. Il est appelé comme ceci :
1 echo pipeline(’affiche_milieu’,array(
2 ^^I’args’=>array(’exec’=>’nom_du_exec’,’id_objet’=>$id_objet),
3 ^^I’data’=>’’));
17.10.1 Exemple
Le plugin « Sélection d’articles » l’utilise pour ajouter un formulaire dans la page des rubriques afin de créer une sélection d’articles :
1 function pb_selection_affiche_milieu($flux) {
2 ^^I$exec = $flux[”args”][”exec”];
3
4 ^^Iif ($exec == ”naviguer”) {
5 ^^I^^I$id_rubrique = $flux[”args”][”id_rubrique”];
6 ^^I^^I$contexte = array(’id_rubrique’=>$id_rubrique);
7 ^^I^^I$ret = ”
8 ^^I^^I$ret .= recuperer_fond(”selection_interface”, $contexte);
9 ^^I^^I$ret .= ”
10 ^^I^^I$flux[”data”] .= $ret;
11 ^^I}
12
13 ^^Ireturn $flux;
14 }
Le plugin « statistiques » (en développement pour la prochaine version de SPIP) l’utilise pour ajouter un formulaire de configuration dans les pages de configu- ration de SPIP :
1 function stats_affiche_milieu($flux){
2 ^^I// afficher la configuration ([des]activer les statistiques).
3 ^^Iif ($flux[’args’][’exec’] == ’config_fonctions’) {
4 ^^I^^I$compteur = charger_fonction(’compteur’, ’configuration’);
5 ^^I^^I$flux[’data’] .= $compteur();
6 ^^I}
7 ^^Ireturn $flux;
8 }
17.11 declarer_tables_objets_surnoms
Il permet d’indiquer la relation entre le type d’objet et sa correspondance SQL. Par défaut, un ’s’ de pluriel est ajouté (l’objet ’article’ donne une table SQL ’arti- cles’). Le pipeline reçoit un tableau des correspondances de SPIP. Appel du pipeline :
1 $surnoms = pipeline(’declarer_tables_objets_surnoms’,
2 ^^Iarray(
3 ^^I^^I’article’ => ’articles’,
4 ^^I^^I’auteur’ => ’auteurs’,
5 ^^I^^I//...
6 ^^I));
Ces correspondances permeent aux fonctions table_objet() et objet_type() de retrouver l’un et l’autre : 17.12. STYLISER 151
1 // type...
2 $type = objet_type(’spip_articles’); // article
3 $type = objet_type(’articles’); // article
4 // table...
5 $objet = table_objet(’article’); // articles
6 $table = table_objet_sql(’article’); // spip_articles
7 // id...
8 $_id_objet = id_table_objet(’articles’); // id_article
9 $_id_objet = id_table_objet(’spip_articles’); // id_article
10 $_id_objet = id_table_objet(’article’); // id_article
17.11.1 Exemple
Le plugin « jeux » déclare sa relation de la sorte :
1 function jeux_declarer_tables_objets_surnoms($surnoms) {
2 ^^I$surnoms[’jeu’] = ’jeux’;
3 ^^Ireturn $surnoms;
4 }
17.12 styliser
Ce pipeline permet de modifier la façon dont SPIP cherche les squelees utilisés pour générer une page. Il est possible par exemple, d’aiguiller vers un squelee spécifique en fonction d’une rubrique donnée. Ce pipeline est appelé comme suit :
1 // pipeline styliser
2 $squelette = pipeline(’styliser’, array(
3 ^^I’args’ => array(
4 ^^I^^I’id_rubrique’ => $id_rubrique,
5 ^^I^^I’ext’ => $ext,
6 ^^I^^I’fond’ => $fond, 152 CHAPITRE 17. LISTE DES PIPELINES
7 ^^I^^I’lang’ => $lang,
8 ^^I^^I’connect’ => $connect
9 ^^I),
10 ^^I’data’ => $squelette,
11 ));
Il reçoit donc des arguments connus de l’environnement et retourne un nom de squelee qui sera utilisé pour la compilation. Ainsi, en appelant une page spip.php?article18, on recevrait les arguments
• id_rubrique = 4 (si l’article est dans la rubrique 4)
• ext = ’html’ (extension par défaut des squelees SPIP)
• fond = ’article’ (nom du fond demandé)
• lang = ’fr’
• connect = ” (nom de la connexion SQL utilisée).
17.12.1 Exemple
Le plugin « SPIP Clear » utilise ce pipeline pour appeler des squelees spécifiques sur les secteurs utilisés par ce moteur de blog :
1 // définir le squelette a utiliser si on est dans le cas d’une rubrique de spipClear
2 function spipclear_styliser($flux){
3 ^^I// si article ou rubrique
4 ^^Iif (($fond = $flux[’args’][’fond’])
5 ^^IAND in_array($fond, array(’article’,’rubrique’))) {
6
7 ^^I^^I$ext = $flux[’args’][’ext’];
8 ^^I^^I// [...]
9 ^^I^^Iif ($id_rubrique = $flux[’args’][’id_rubrique’]) {
10 ^^I^^I^^I// calcul du secteur
11 ^^I^^I^^I$id_secteur = sql_getfetsel(’id_secteur’, ’spip_rubriques’, ’id_rubrique=’ . intval($id_rubrique));
12 ^^I^^I^^I// comparaison du secteur avec la config de SPIP Clear
13 ^^I^^I^^Iif (in_array($id_secteur, lire_config(’spipclear/secteurs’, 1))) { 17.13. JQUERY_PLUGINS 153
14 ^^I^^I^^I^^I// si un squelette $fond_spipclear existe
15 ^^I^^I^^I^^Iif ($squelette = test_squelette_spipclear($fond, $ext)) {
16 ^^I^^I^^I^^I^^I$flux[’data’] = $squelette;
17 ^^I^^I^^I^^I}
18 ^^I^^I^^I}
19 ^^I^^I}
20 ^^I}
21 ^^Ireturn $flux;
22 }
23
24 // retourne un squelette $fond_spipclear.$ext s’il existe
25 function test_squelette_spipclear($fond, $ext) {
26 ^^Iif ($squelette = find_in_path($fond.”_spipclear.$ext”)) {
27 ^^I^^Ireturn substr($squelette, 0, -strlen(”.$ext”));
28 ^^I}
29 ^^Ireturn false;
30 }
17.13 jquery_plugins
Ce pipeline permet d’ajouter très simplement dans les pages privées et publiques (ayant une balise #INSERT_HEAD (p. 34)) des scripts JavaScript. Ce pipeline reçoit et retourne un tableau d’adresses de fichiers à insérer et est appelé comme suit :
1 $scripts = pipeline(’jquery_plugins’, array(
2 ^^I’javascript/jquery.js’,
3 ^^I’javascript/jquery.form.js’,
4 ^^I’javascript/ajaxCallback.js’
5 )); 154 CHAPITRE 17. LISTE DES PIPELINES
17.13.1 Exemple
Ajouter le script « jquery.cycle.js » sur toutes les pages :
1 function prefixPlugin_jquery_plugins($scripts){
2 ^^I$scripts[] = ”javascript/jquery.cycle.js”;
3 ^^Ireturn $scripts;
4 }
17.14 post_insertion
Ce pipeline est un déclencheur (« trigger ») qui s’exécute après l’insertion de nou- veaux éléments dans la base de données. Il permet donc d’effectuer des actions post insertions. Le pipeline transmet le nom de la table, l’identifiant créé et un tableau des champs et valeurs insérées :
1 pipeline(’post_insertion’,
2 ^^Iarray(
3 ^^I^^I’args’ => array(
4 ^^I^^I^^I’table’ => ’spip_articles’,
5 ^^I^^I^^I’id_objet’ => $id_article
6 ^^I^^I),
7 ^^I^^I’data’ => $champs
8 ^^I)
9 );
17.14.1 Exemple
Pour chaque article nouvellement créé, lier automatiquement le mot clé 248 : 17.15. FORMULAIRE_CHARGER 155
1 function ajoutmot_post_insertion($flux) {
2 ^^Iif ($flux[’args’][’table’] == ’spip_articles’) {
3 ^^I^^Isql_insertq(”spip_mots_articles”, array(
4 ^^I^^I^^I’id_mot’ => 248,
5 ^^I^^I^^I’id_article’ =>$flux[’args’][’id_objet’]));
6 ^^I}
7 ^^Ireturn $flux;
8 }
17.15 formulaire_arger
Le pipeline formulaire_charger permet de modifier le tableau de valeurs en- voyé par la fonction charger d’un formulaire CVT. Il est donc appelé lors de l’affichage d’un formulaire dans le fichier ecrire/balise/formulaire_.php Il reçoit en argument le nom du formulaire ainsi que les paramètres transmis dans les fonctions charger, verifier et traiter. Il retourne le tableau des valeurs à charger.
1 $valeurs = pipeline(
2 ^^I’formulaire_charger’,
3 ^^Iarray(
4 ^^I^^I’args’=>array(’form’=>$form,’args’=>$args),
5 ^^I^^I’data’=>$valeurs)
6 );
17.15.1 Exemple
Le plugin « noSpam » se sert de ce pipeline pour ajouter un jeton indiquant une durée de validité sur les formulaires sélectionnés par une variable globale :
1 $GLOBALS[’formulaires_no_spam’][] = ’forum’;
2 // 156 CHAPITRE 17. LISTE DES PIPELINES
3 function nospam_formulaire_charger($flux){
4 ^^I$form = $flux[’args’][’form’];
5 ^^Iif (in_array($form, $GLOBALS[’formulaires_no_spam’])){
6 ^^I^^Iinclude_spip(”inc/nospam”);
7 ^^I^^I$jeton = creer_jeton($form);
8 ^^I^^I$flux[’data’][’_hidden’] .= ””;
9 ^^I}
10 ^^Ireturn $flux;
11 }
17.16 editer_contenu_objet
Ce pipeline est appelé au moment de l’affichage d’un formulaire d’édition d’un objet de SPIP. Il permet de modifier le contenu HTML du formulaire. Ce pipeline est appelé comme paramètre de chargement d’un formulaire CVT (p. 286):
1 $contexte[’_pipeline’] = array(’editer_contenu_objet’, array(’type’=>$type, ’id’=>$id));
Le pipeline transmet :
• le type (type) , l’identifiant de l’objet (id) et le contexte de compilation (tableau contexte) dans le tableau args
• le code HTML dans la clé data
17.16.1 Exemple
Le plugin « OpenID » ajoute un champ de saisie dans le formulaire d’édition des auteurs :
1 function openid_editer_contenu_objet($flux){
2 ^^Iif ($flux[’args’][’type’]==’auteur’) {
3 ^^I^^I$openid = recuperer_fond(’formulaires/inc-openid’, $flux[’args’][’contexte’]); 17.17. RUBRIQUE_ENCOURS 157
4 ^^I^^I$flux[’data’] = preg_replace(’%(
5 ^^I}
6 ^^Ireturn $flux;
7 }
17.17 rubrique_encours
Il permet d’ajouter du contenu dans le cadre « Proposés à publication » des rubriques. Ce cadre s’affiche uniquement si au moins un élément (article, site, brève…) dans la rubrique est proposé à publication. Il est appellé dans ecrire/exec/naviguer.php :
1 pipeline(’rubrique_encours’, array(
2 ^^I’args’ => array(’type’ => ’rubrique’, ’id_objet’ => $id_rubrique),
3 ^^I’data’ => $encours));
17.17.1 Exemple
Le plugin « Forum » l’utilise pour ajouter une phrase suggérant de commenter les articles proposés à la publication :
1 function forum_rubrique_encours($flux){
2 ^^Iif (strlen($flux[’data’])
3 ^^I AND $GLOBALS[’meta’][’forum_prive_objets’] != ’non’)
4 ^^I^^I$flux[’data’] = _T(’texte_en_cours_validation_forum’) . $flux[’data’];
5 ^^Ireturn $flux;
6 } 158 CHAPITRE 17. LISTE DES PIPELINES 17.18 pre_insertion
Il permet d’ajouter des contenus par défaut au moment de la création d’un nouvel élément éditorial dans la base de données. Lorsqu’on enregistre un élément éditorial, si celui ci n’a pas encore d’identifiant (il est donc nouveau), un identifiant est crée pour cet élément, via les fonctions insert_xx où xx est le nom de l’objet souhaité. Cee insertion a simplement pour objectif de retourner un identifiant et d’enregistrer les valeurs par défaut de l’élément. Ce pipeline est appelé dans ces fonctions insert_xx. Une fois l’identifiant connu, les taches de modifications normales sont effec- tuées, via les fonctions xx_set et modifier_contenu qui appelle les pipelines pre_edition et post_edition. Ce sont elles qui enregistreront les données pos- tées par l’utilisateur, et cela donc, même pour un nouvel élément. Le pipeline transmet le nom de la table et un tableau des champs et valeurs par défaut à insérer :
1 $champs = pipeline(’pre_insertion’,
2 ^^Iarray(
3 ^^I^^I’args’ => array(
4 ^^I^^I^^I’table’ => ’spip_rubriques’,
5 ^^I^^I),
6 ^^I^^I’data’ => $champs
7 ^^I)
8 );
17.18.1 Exemple
Le plugin « Forum » ajoute au moment d’une insertion la valeur du statut des forums d’un article comme ceci :
1 function forum_pre_insertion($flux){
2 ^^Iif ($flux[’args’][’table’]==’spip_articles’){
3 ^^I^^I$flux[’args’][’data’][’accepter_forum’] =^^Isubstr($GLOBALS[’meta’][’forums_publics’], 0, 3);
4 ^^I} 17.19. AFFICHER_FICHE_OBJET 159
5 ^^Ireturn $flux;
6 }
17.19 affier_fie_objet
Ce pipeline permet d’ajouter du contenu dans les pages de vues des objets édito- riaux de l’espace privé. Il est appelé comme ceci :
1 pipeline(’afficher_fiche_objet’, array(
2 ^^I’args’ => array(
3 ^^I^^I’type’ => ’type_objet’,
4 ^^I^^I’id’ => $id_objet),
5 ^^I’data’ => ”
Il est pour l’instant déclaré sur les pages « articles » et « navigation » (rubriques).
17.19.1 Exemple
Le plugin « Forum » l’utilise pour ajouter les boutons pour discuter d’un article. Il ajoute donc un forum au pied de l’article :
1 function forum_afficher_fiche_objet($flux){
2 ^^Iif (($type = $flux[’args’][’type’])==’article’){
3 ^^I^^I$id = $flux[’args’][’id’];
4 ^^I^^I$table = table_objet($type);
5 ^^I^^I$id_table_objet = id_table_objet($type);
6 ^^I^^I$discuter = charger_fonction(’discuter’, ’inc’);
7 ^^I^^I$flux[’data’] .= $discuter($id, $table, $id_table_objet, ’prive’, _request(’debut’));
8 ^^I}
9 ^^I// [...]
10 ^^Ireturn $flux;
11 } 160 CHAPITRE 17. LISTE DES PIPELINES 17.20 optimiser_base_disparus
Appelé depuis ecrire/genie/optimiser.php, il permet de compléter le neoyage des objets orphelins, en supprimant des éléments lors des taches périodiques.
1 $n = pipeline(’optimiser_base_disparus’, array(
2 ^^I^^I’args’=>array(
3 ^^I^^I^^I’attente’ => $attente,
4 ^^I^^I^^I’date’ => $mydate),
5 ^^I^^I’data’=>$n
6 ));
Il reçoit la durée d’aente entre 2 optimisations, ainsi que la date de péremption correspondante. Dans l’argument « data » se stocke le nombre d’éléments sup- primés. La fonction optimiser_sansref() permet de gérer la suppression des éléments en donnant 3 arguments :
• la table,
• la clé primaire,
• un résultat de requête SQL contenant uniquement une colonne « id » dé- finissant les identifiants à effacer.
17.20.1 Exemple
Pour supprimer les forums appartenant à une rubrique disparue, le plugin « Fo- rum » l’utilise comme ceci :
1 function forum_optimiser_base_disparus($flux){
2 $n = &$flux[’data’];
3
4 # les forums lies a une id_rubrique inexistante
5 $res = sql_select(”forum.id_forum AS id”,
6 ”spip_forum AS forum
7 LEFT JOIN spip_rubriques AS rubriques 17.21. AFFICHER_CONFIG_OBJET 161
8 ON forum.id_rubrique=rubriques.id_rubrique”,
9 ”rubriques.id_rubrique IS NULL
10 AND forum.id_rubrique>0”);
11
12 $n+= optimiser_sansref(’spip_forum’, ’id_forum’, $res);
13
14 // [...]
15
16 return $flux;
17 }
17.21 affier_config_objet
Ce pipeline permet d’ajouter des éléments dans un cadre de configuration des objets de SPIP. Il est appelé comme cela dans ecrire/exec/articles.php :
1 $masque = pipeline(’afficher_config_objet’,
2 ^^Iarray(’args’ => array(’type’=>’type objet’, ’id’=>$id_objet),
3 ^^I’data’=>$masque));
Il s’applique pour le moment uniquement sur les articles et ajoute son contenu dans le cadre « Forum et Pétitions ».
17.21.1 Exemple
Le plugin « Forum » ajoute les réglages de modération (pas de forum, forum sur abonnement, forum libre…) pour chaque article comme ceci :
1 function forum_afficher_config_objet($flux){
2 ^^Iif (($type = $flux[’args’][’type’]) == ’article’){
3 ^^I^^I$id = $flux[’args’][’id’]; 162 CHAPITRE 17. LISTE DES PIPELINES
4 ^^I^^Iif (autoriser(’modererforum’, $type, $id)) {
5 ^^I^^I^^I$table = table_objet($type);
6 ^^I^^I^^I$id_table_objet = id_table_objet($type);
7 ^^I^^I^^I$flux[’data’] .= recuperer_fond( ”prive/configurer/moderation”, array($id_table_objet => $id));
8 ^^I^^I}
9 ^^I}
10 ^^Ireturn $flux;
11 }
17.22 body_prive
Ce pipeline permet de modifier la balise HTML body de l’espace privé ou d’ajou- ter du contenu juste après cee balise. Il est appelé par la fonction commencer_page() exécutée lors de l’affichage des pages privées.
1 $res = pipeline(’body_prive’,
2 ^^I”
3 ^^I. ($GLOBALS[’spip_lang_rtl’] ? ” dir=’rtl’” : ””) . ’>’);
17.23 accueil_encours
Ce pipeline permet d’ajouter du contenu au centre de la page d’accueil de l’espace privé, par exemple pour afficher les nouveaux articles proposés à la publication.
1 $res = pipeline(’accueil_encours’, $res);
Ce pipeline reçoit un texte et retourne le texte complété. 17.24. ACCUEIL_GADGET 163
17.23.1 Exemple
Le plugin « breves », s’il existait, l’utiliserait pour ajouter la liste des dernières brèves proposées :
1 function breves_accueil_encours($texte){
2 ^^I$texte .= afficher_objets(’breve’, afficher_plus(generer_url_ecrire(’breves’)) . _T(’info_breves_valider’), array(”FROM” => ’spip_breves’, ’WHERE’ => ”statut=’prepa’ OR statut=’prop’”, ’ORDER BY’ => ”date_heure DESC”), true);
3 ^^Ireturn $texte;
4 }
17.24 accueil_gadget
Ce pipeline permet d’ajouter des liens en haut du contenu de la page d’accueil de l’espace privé, dans le cadre qui liste différentes actions possibles (créer une rubrique, un article, une brève…).
1 $gadget = pipeline(’accueil_gadgets’, $gadget);
Ce pipeline reçoit un texte et retourne le texte complété.
17.24.1 Exemple
Le plugin « breves », s’il existait, l’utiliserait pour ajouter un lien pour créer ou voir la liste des brèves en fonction du statut de l’auteur connecté :
1 function breves_accueil_gadgets($texte){
2 ^^Iif ($GLOBALS[’meta’][’activer_breves’] != ’non’) {
3 ^^I^^I// creer sinon voir
4 ^^I^^Iif ($GLOBALS[’visiteur_session’][’statut’] == ”0minirezo”) {
5 ^^I^^I^^I$ajout = icone_horizontale(_T(’icone_nouvelle_breve’), generer_url_ecrire(”breves_edit”,”new=oui”), ”breve-24.png”,”new”, false);
6 ^^I^^I} else { 164 CHAPITRE 17. LISTE DES PIPELINES
7 ^^I^^I^^I$ajout = icone_horizontale (_T(’icone_breves’), generer_url_ecrire(”breves”,””), ”breve-24.png”, ””, false);
8 ^^I^^I}
9 ^^I^^I$texte = str_replace(””, ”
10 ^^I}
11 ^^Ireturn $texte;
12 }
17.25 accueil_informations
Ce pipeline permet d’ajouter des informations sur les objets éditoriaux dans la navigation latérale de la page d’accueil.
1 $res = pipeline(’accueil_informations’, $res);
Il prend un texte en paramètre qu’il peut compléter et qu’il retourne.
17.25.1 Exemple
Le plugin « breves », s’il existait, pourrait l’utiliser pour ajouter le nombre de brèves en aente de validation :
1 function breves_accueil_informations($texte){
2 ^^Iinclude_spip(’base/abstract_sql’);
3 ^^I$q = sql_select(”COUNT(*) AS cnt, statut”, ’spip_breves’, ’’, ’statut’, ’’,’’, ”COUNT(*)<>0”);
4 ^^I// traitements sur le texte en fonction du resultat
5 ^^I// ...
6 ^^Ireturn $texte;
7 } 17.26. AFFICHAGE_FINAL 165 17.26 affiage_final
Ce pipeline est appelé au moment de l’envoi du contenu d’une page au naviga- teur. Il reçoit un texte (la page HTML le plus souvent) qu’il peut compléter. Les modifications ne sont pas mises en cache par SPIP.
1 echo pipeline(’affichage_final’, $page[’texte’]);
C’est un pipeline fréquemment utilisé par les plugins permeant une grande va- riété d’actions. Cependant, comme le résultat n’est pas mis en cache, et que le pipeline est appelé à chaque page affichée, il faut être prudent et le réserver à des utilisations peu gourmandes en ressources.
17.26.1 Exemple
Le plugin « XSPF », qui permet de réaliser des galeries multimédias, ajoute un javascript uniquement sur les pages qui le nécessitent, de cee façon :
1 function xspf_affichage_final($page) {
2 ^^I// on regarde rapidement si la page a des classes player
3 ^^Iif (strpos($page, ’class=”xspf_player”’)===FALSE)
4 ^^I^^Ireturn $page;
5
6 ^^I// Si oui on ajoute le js de swfobject
7 ^^I$jsFile = find_in_path(’lib/swfobject/swfobject.js’);
8 ^^I$head = ””;
9 ^^I$pos_head = strpos($page, ’’);
10 ^^Ireturn substr_replace($page, $head, $pos_head, 0);
11 }
Le plugin « target » lui, ouvre les liens extérieurs dans une nouvelle fenêtre (oui, c’est très mal !) :
1 function target_affichage_final($texte) {
2 ^^I$texte = str_replace(’spip_out”’, ’spip_out” target=”_blank”’, $texte); 166 CHAPITRE 17. LISTE DES PIPELINES
3 ^^I$texte = str_replace(’rel=”directory”’, ’rel=”directory” class=”spip_out” target=”_blank”’, $texte);
4 ^^I$texte = str_replace(’spip_glossaire”’, ’spip_glossaire” target=”_blank”’, $texte);
5 ^^Ireturn $texte;
6 }
17.27 affie_droite
Ce pipeline permet d’ajouter du contenu dans la colonne « droite » (qui n’est d’ailleurs pas forcément à droite – c’est en fonction des préférences et de la langue de l’utilisateur) des pages « exec » de l’espace privé. Cee colonne contient généralement des liens de navigation transversale en relation avec le contenu af- fiché, comme le cadre « dans la même rubrique » qui liste les derniers articles publiés.
1 echo pipeline(’affiche_droite’, array(
2 ^^I’args’=>array(
3 ^^I^^I’exec’=>’naviguer’,
4 ^^I^^I’id_rubrique’=>$id_rubrique),
5 ^^I’data’=>’’));
Ce pipeline reçoit le nom de la page « exec » affichée ainsi que, s’il y a lieu, l’identifiant de l’objet en cours de lecture, comme ici « id_rubrique ».
17.27.1 Exemple
Le plugin « odt2spip » qui permet de créer des articles SPIP à partir de documents Open Office Texte (extension .odt) utilise ce pipeline pour ajouter un formulaire dans la vue des rubriques afin d’envoyer le fichier odt :
1 function odt2spip_affiche_droite($flux){
2 ^^I$id_rubrique = $flux[’args’][’id_rubrique’];
3 ^^Iif ($flux[’args’][’exec’]==’naviguer’ AND $id_rubrique > 0) { 17.28. AFFICHE_GAUCHE 167
4 ^^I^^I$icone = icone_horizontale(_T(”odtspip:importer_fichier”), ”#”, ””, _DIR_PLUGIN_ODT2SPIP . ”images/odt-24.png”, false, ”onclick=’$(\”#boite_odt2spip\”).slideToggle(\”fast\”); return false;’”);
5 ^^I^^I$out = recuperer_fond(’formulaires/odt2spip’, array(’id_rubrique’=>$id_rubrique, ’icone’=>$icone));
6 ^^I^^I$flux[’data’] .= $out;
7 ^^I}
8 ^^Ireturn $flux;
9 }
17.28 affie_gaue
Ce pipeline permet d’ajouter du contenu dans la colonne « gauche » des pages de l’espace privé. Cee colonne contient généralement des liens ou des formulaires en relation avec le contenu affiché, tel que le formulaire d’ajout de logo.
1 echo pipeline(’affiche_gauche’, array(
2 ^^I’args’=>array(
3 ^^I^^I’exec’=>’articles’,
4 ^^I^^I’id_article’=>$id_article),
5 ^^I’data’=>’’));
Ce pipeline reçoit le nom de la page « exec » affichée ainsi que, s’il y a lieu, l’identifiant de l’objet en cours de lecture, comme ici « id_article ».
17.28.1 Exemple
Le plugin « spip bisous », qui permet d’envoyer des bisous ( !) entre les auteurs, utilise ce pipeline pour afficher la liste des bisous reçus et envoyés sur les pages des auteurs :
1 function bisous_affiche_gauche($flux){
2 ^^Iinclude_spip(’inc/presentation’);
3
4 ^^Iif ($flux[’args’][’exec’] == ’auteur_infos’){ 168 CHAPITRE 17. LISTE DES PIPELINES
5 ^^I^^I$flux[’data’] .=
6 ^^I^^Idebut_cadre_relief(’’,true,’’, _T(’bisous:bisous_donnes’)) .
7 ^^I^^Irecuperer_fond(’prive/bisous_donnes’, array(’id_auteur’=>$flux[’args’][’id_auteur’])) .
8 ^^I^^Ifin_cadre_relief(true) .
9 ^^I^^Idebut_cadre_relief(’’,true,’’, _T(’bisous:bisous_recus’)) .
10 ^^I^^Irecuperer_fond(’prive/bisous_recus’, array(’id_auteur’=>$flux[’args’][’id_auteur’])) .
11 ^^I^^Ifin_cadre_relief(true);
12 ^^I}
13 ^^Ireturn $flux;
14 }
17.29 affie_hierarie
Le pipeline « affiche_hierarchie » permet de modifier ou compléter le code HTML du fil d’ariane de l’espace privé. Il reçoit un certain nombre d’informations dans args : l’objet et son identifiant en cours de lecture s’il y a lieu, éventuellement l’identifiant du secteur.
1 $out = pipeline(’affiche_hierarchie’, array(
2 ^^I’args’=>array(
3 ^^I^^I’id_parent’=>$id_parent,
4 ^^I^^I’message’=>$message,
5 ^^I^^I’id_objet’=>$id_objet,
6 ^^I^^I’objet’=>$type,
7 ^^I^^I’id_secteur’=>$id_secteur,
8 ^^I^^I’restreint’=>$restreint),
9 ^^I’data’=>$out));
17.29.1 Exemple
Le plugin « polyhiérarchie » qui autorise une rubrique à avoir plusieurs parents utilise ce pipeline pour lister les différents parents de la rubrique ou de l’article visité : 17.30. AFFICHE_ENFANTS 169
1 function polyhier_affiche_hierarchie($flux){
2 ^^I$objet = $flux[’args’][’objet’];
3 ^^Iif (in_array($objet,array(’article’,’rubrique’))){
4 ^^I^^I$id_objet = $flux[’args’][’id_objet’];
5 ^^I^^Iinclude_spip(’inc/polyhier’);
6 ^^I^^I$parents = polyhier_get_parents($id_objet,$objet,$serveur=’’);
7 ^^I^^I$out = array();
8 ^^I^^Iforeach($parents as $p)
9 ^^I^^I^^I$out[] = ”[->rubrique$p]”;
10 ^^I^^Iif (count($out)){
11 ^^I^^I^^I$out = implode(’, ’,$out);
12 ^^I^^I^^I$out = _T(’polyhier:label_autres_parents’).” ”.$out;
13 ^^I^^I^^I$out = PtoBR(propre($out));
14 ^^I^^I^^I$flux[’data’] .= ”
15 ^^I^^I}
16
17 ^^I}
18 ^^Ireturn $flux;
19 }
17.30 affie_enfants
Ce pipeline permet d’ajouter ou de modifier le contenu des listes présentant les enfants d’un objet. Il reçoit dans args le nom de la page en cours et l’identifiant de l’objet, et dans data le code HTML présentant les enfants de l’objet. Ce pipeline n’est appelé actuellement qu’à un seul endroit : sur la page de navigation des rubriques.
1 $onglet_enfants = pipeline(’affiche_enfants’, array(
2 ^^I’args’=>array(
3 ^^I^^I’exec’=>’naviguer’,
4 ^^I^^I’id_rubrique’=>$id_rubrique),
5 ^^I’data’=>$onglet_enfants)); 170 CHAPITRE 17. LISTE DES PIPELINES 17.31 autoriser
Le pipeline « autoriser » est particulier. Il permet simplement de charger des fonctions d’autorisations au tout premier appel de la fonction autoriser(). Ce pipeline ne transmet rien et ne reçoit rien.
1 pipeline(’autoriser’);
Grâce à lui, un plugin peut déclarer des autorisations spécifiques, regroupées dans un fichier « prefixePlugin_autorisations.php » et les déclarer, dans plugin.xml comme ceci :
1
2 ^^I
3 ^^I
4
Outre les fonctions d’autorisations, le fichier doit contenir la fonction appelée par tous les pipelines (« prefixePlugin_nomDuPipeline() ») mais elle n’a rien a effectuer. Un exemple :
1 function prefixePlugin_autoriser(){}
17.31.1 Exemple
Le plugin « forum » déclare quelques autorisations. Son fichier plugin.xml contient :
1
2 ^^I
3 ^^I
4
Et le fichier appelé, « forum_autoriser.php » contient : 17.32. AJOUTER_BOUTONS 171
1 // declarer la fonction du pipeline
2 function forum_autoriser(){}
3
4 function autoriser_forum_interne_suivi_bouton_dist($faire, $type, $id, $qui, $opt) {
5 ^^Ireturn true;
6 }
7
8 function autoriser_forum_reactions_bouton_dist(($faire, $type, $id, $qui, $opt) {
9 ^^Ireturn autoriser(’publierdans’, ’rubrique’, _request(’id_rubrique’));
10 }
11
12 // Moderer le forum ?
13 // = modifier l’objet correspondant (si forum attache a un objet)
14 // = droits par defaut sinon (admin complet pour moderation complete)
15 function autoriser_modererforum_dist($faire, $type, $id, $qui, $opt) {
16 ^^Ireturn autoriser(’modifier’, $type, $id, $qui, $opt);
17 }
18
19 // Modifier un forum ? jamais !
20 function autoriser_forum_modifier_dist($faire, $type, $id, $qui, $opt) {
21 ^^Ireturn false;
22 }
23 ...
17.32 ajouter_boutons
Ce pipeline permet d’ajouter des boutons dans le menu de navigation de l’espace privé. Il n’a plus vraiment d’utilité depuis la création du tag
1 $boutons_admin = pipeline(’ajouter_boutons’, $boutons_admin);
Le pipeline « ajouter_boutons » reçoit un tableau associatif « identifiant d’un bouton / description du bouton » (classe PHP Bouton). Un bouton peut déclarer un sous-menu dans la variable « sousmenu » de la classe Bouton. Il faut créer une instance de la classe Bouton pour définir celui-ci : 172 CHAPITRE 17. LISTE DES PIPELINES
1 function plugin_ajouter_boutons($boutons_admin){
2 $boutons_admin[’identifiant’] =
3 ^^Inew Bouton(’image/du_bouton.png’, ’Titre du bouton’, ’url’);
4 $boutons_admin[’identifiant’]->sousmenu[’autre_identifiant’] =
5 ^^Inew Bouton(’image/du_bouton.png’, ’Titre du bouton’, ’url’);
6 return $boutons_admin;
7 }
Le troisième paramètre url de la classe Bouton est optionnel. Par défaut ce sera une page « exec » de même nom que l’identifiant donné (ecrire/?exec=identifiant).
17.32.1 Exemple
Le plugin « elia » qui permet d’interfacer SPIP avec le logiciel élia, utilise ce pipeline pour ajouter au menu « Édition » (identifiant « naviguer ») un lien vers le catalogue élia :
1 function spip_thelia_ajouter_boutons($boutons_admin) {
2 ^^I// si on est admin
3 ^^Iif ($GLOBALS[’visiteur_session’][’statut’] == ”0minirezo”) {
4 ^^I^^I$boutons_admin[’naviguer’]->sousmenu[’spip_thelia_catalogue’] =
5 ^^I^^Inew Bouton(_DIR_PLUGIN_SPIP_THELIA . ’img_pack/logo_thelia_petit.png’, ’Catalogue Thélia’);
6 ^^I}
7 ^^Ireturn $boutons_admin;
8 }
Migration vers la nouvelle écriture Pour migrer cet exemple dans la nouvelle écriture, il faut séparer 2 choses : la déclaration du bouton et l’autorisation de le voir ou non (ici seulement si l’on est administrateur). La déclaration s’écrit dans le fichier plugin.xml :
1
2 ^^I
3 ^^I
4 17.33. AJOUTER_ONGLETS 173
L’autorisation passe par une fonction d’autorisation spécifique (utiliser le pipe- line autoriser (p. 170) pour la définir) :
1 function autoriser_spip_thelia_catalogue_bouton_dist($faire, $type, $id, $qui, $opt) {
2 ^^Ireturn ($qui[’statut’] == ’0minirezo’);
3 }
17.33 ajouter_onglets
Ce pipeline permet d’ajouter des onglets dans les pages exec de l’espace privé. Il n’a plus vraiment d’utilité depuis la création du tag
1 return pipeline(’ajouter_onglets’, array(’data’=>$onglets,’args’=>$script));
Le pipeline « ajouter_onglets » reçoit un tableau associatif « identifiant de l’on- glet / description de l’onglet » (classe PHP Bouton), mais aussi un identifiant de barre d’onglet (dans args).
1 // ajout d’un onglet sur la page de configuration de SPIP
2 function plugin_ajouter_onglets($flux){
3 ^^Iif ($flux[’args’]==’identifiant’)
4 ^^I^^I$flux[’data’][’identifiant_bouton’]= new Bouton(”mon/image.png”, ”titre de l’onglet”), ’url’);
5 ^^Ireturn $flux;
6 }
Le troisième paramètre url de la classe Bouton est optionnel. Par défaut ce sera une page « exec » de même nom que l’identifiant donné (ecrire/?exec=identifiant).
Dans les pages exec, une barre d’outil s’appelle avec deux arguments : l’identi- fiant de la barre désirée et l’identifiant de l’onglet actif :
1 echo barre_onglets(”identifiant barre d’onglet”, ”identifiant de l’onglet actif”);
2 echo barre_onglets(”configuration”, ”contenu”); 174 CHAPITRE 17. LISTE DES PIPELINES
17.33.1 Exemple
Le plugin « Agenda » modifie les onglets par défaut du calendrier de SPIP en utilisant ce pipeline :
1 function agenda_ajouter_onglets($flux) {
2 if($flux[’args’]==’calendrier’){
3 ^^I$flux[’data’][’agenda’]= new Bouton(
4 ^^I^^I_DIR_PLUGIN_AGENDA . ’/img_pack/agenda-24.png’,
5 ^^I^^I_T(’agenda:agenda’),
6 ^^I^^Igenerer_url_ecrire(”calendrier”,”type=semaine”));
7 ^^I$flux[’data’][’calendrier’] = new Bouton(
8 ^^I ^^I’cal-rv.png’,
9 ^^I^^I_T(’agenda:activite_editoriale’),
10 ^^I^^Igenerer_url_ecrire(”calendrier”, ”mode=editorial&type=semaine”));
11 }
12 return $flux;
13 }
Migration vers la nouvelle écriture _ Pour migrer cet exemple dans la nouvelle écriture, il faut séparer 2 choses : la déclaration du bouton et l’autorisation de le voir ou non. La déclaration s’écrit dans le fichier plugin.xml :
1
2 ^^I
3 ^^I
4 ^^I
5 ^^I
6
7
8 ^^I
9 ^^I
10 ^^I
11 ^^I
12 17.34. RECUPERER_FOND 175
L’autorisation passe par une fonction spécifique (utiliser le pipeline autoriser (p. 170) pour la définir) :
1 function autoriser_calendrier_onglet_dist($faire, $type, $id, $qui, $opt) {
2 ^^Ireturn true;
3 }
4 function autoriser_agenda_onglet_dist($faire, $type, $id, $qui, $opt) {
5 ^^Ireturn true;
6 }
17.34 recuperer_fond
Le pipeline « recuperer_fond » permet de compléter ou modifier le résultat de la compilation d’un squelee donné. Il reçoit le nom du fond sélectionné et le contexte de compilation dans args, ainsi que le tableau décrivant le résultat dans data.
1 $page = pipeline(’recuperer_fond’, array(
2 ^^I’args’=>array(
3 ^^I^^I’fond’=>$fond,
4 ^^I^^I’contexte’=>$contexte,
5 ^^I^^I’options’=>$options,
6 ^^I^^I’connect’=>$connect),
7 ^^I’data’=>$page));
Bien souvent, seule la clé texte du tableau data sera modifiée. Se reporter à la fonction recuperer_fond() (p. 122) pour obtenir une description de ce tableau.
17.34.1 Exemple
Le plugin « login » permet de s’identifier en passant par Facebook. Il ajoute un bouton sur le formulaire d’identification habituel de SPIP. Le pipeline « so- 176 CHAPITRE 17. LISTE DES PIPELINES
cial_login_links » (du même plugin) renvoie le code HTML d’un lien pointant sur l’identification de Facebook.
1 function fblogin_recuperer_fond($flux){
2 ^^Iif ($flux[’args’][’fond’] == ’formulaires/login’){
3 ^^I^^I$login = pipeline(’social_login_links’, ’’);
4 ^^I^^I$flux[’data’][’texte’] = str_replace(’’, ’’ . $login, $flux[’data’][’texte’]);
5 ^^I}
6 ^^Ireturn $flux;
7 }
17.35 header_prive
Le pipeline header_prive permet d’ajouter des contenus dans la partie
des pages de l’espace privé. Il fonctionne comme le pipeline insert_head (p. 141). Le pipeline reçoit le contenu du HEAD et le retourne :1 function prefixPlugin_header_prive($flux){
2 ^^I$flux .= ”\n”;
3 ^^Ireturn $flux;
4 }
17.35.1 Exemple
Le plugin « Notations » se sert de ce point d’entrée pour ajouter une CSS dans l’espace privé et dans l’espace public (avec insert_head):
1 function notation_header_prive($flux){
2 ^^I$flux = notation_insert_head($flux);
3 ^^Ireturn $flux;
4 } 17.36. DECLARER_TABLES_INTERFACES 177
5
6 function notation_insert_head($flux){
7 ^^I$flux .= ’’;
8 ^^Ireturn $flux;
9 }
Le plugin « Open Layers » permeant d’utiliser des cartes Open Street Map l’utilise pour charger les javascripts nécessaires :
1 function openlayer_header_prive($flux){
2 ^^I$flux .= ’
3 ^^I
4 ^^I’;
5 ^^Ireturn $flux;
6 }
17.36 declarer_tables_interfaces
Ce pipeline sert à déclarer des informations relatives aux tables SQL ou à cer- tains champs de ces tables. Il permet de compléter les informations données par ecrire/public/interfaces.php La fonction prend en paramètre le tableau des éléments déclarés, souvent nommé $interface et doit le retourner. Ce tableau est composé de différents éléments eux aussi tabulaires :
• table_des_tables déclare des alias de tables SQL,
• exceptions_des_tables aribue des alias de colonne SQL sur une table donnée,
• table_titre indique la colonne SQL d’un objet servant à définir le titre pour certains types de jeux d’URL
• table_date indique une colonne SQL de type date pour une table SQL donnée, permeant d’utiliser dessus des critères spécifiques (age, age_relatif, …) 178 CHAPITRE 17. LISTE DES PIPELINES
• tables_jointures explicite des jointures possibles entre tables SQL
• exceptions_des_jointures crée des alias de colonnes SQL issus d’une jointure
• table_des_traitements indique des filtres à appliquer systématiquement sur des balises SPIP.
17.36.1 table_des_tables
Déclare des alias pour des tables SQL, relatifs aux déclarations données dans les tables principales ou auxiliaires. En général, tout plugin proposant un nouvel objet éditorial déclare également un alias identique au nom de l’objet. Cela permet d’écrire des boucles
1 // ’nom_declare’ = ’spip_rubriques’, mais sans le prefixe ’spip_’
2 $interface[’table_des_tables’][’alias’] = ’nom_declare’;
3 // exemples
4 $interface[’table_des_tables’][’articles’] = ’articles’; // boucles ARTICLES sur spip_articles
5 $interface[’table_des_tables’][’billets’] = ’articles’; // boucles BILLETS sur spip_articles
17.36.2 exceptions_des_tables
De la même manière que la déclaration d’alias de table SQL, il est possible de déclarer des alias de colonnes SQL. Ces alias peuvent aussi forcer une jointure sur une autre table.
1 // balise #COLONNE_ALIAS ou critere {colonne_alias} dans la boucle concernee
2 $interface[’exceptions_des_tables’][’alias’][’colonne_alias’] = ’colonne’;
3 $interface[’exceptions_des_tables’][’alias’][’colonne_alias’] = array(’table’, ’colonne’);
4 // exemples
5 $interface[’exceptions_des_tables’][’breves’][’date’] = ’date_heure’;
6 $interface[’exceptions_des_tables’][’billets’][’id_billet’] = ’id_article’;
7 $interface[’exceptions_des_tables’][’documents’][’type_document’] = array(’types_documents’
8 , ’titre’); 17.36. DECLARER_TABLES_INTERFACES 179
9 // permet d’utiliser les criteres racine, meme_parent, id_parent
10 $interface[’exceptions_des_tables’][’evenements’][’id_parent’] = ’id_evenement_source’;
11 $interface[’exceptions_des_tables’][’evenements’][’id_rubrique’] = array(’spip_articles’, ’id_rubrique’);
17.36.3 table_titre
Indique quel champ sera utilisé pour générer des titres pour certains jeux d’URL (propre, arborescent…). La chaîne transmise est une déclaration de sélection SQL (SELECT), qui doit renvoyer 2 colonnes (ou alias de colonne SQL) : « titre » et « lang ». Lorsque l’objet n’a pas de champ « lang » correspondant, on doit donc renvoyer ’’ AS lang.
1 $interface[’table_titre’][’alias’]= ”colonne_titre AS titre, colonne_lang AS lang”;
2 // exemples
3 $interface[’table_titre’][’mots’]= ”titre, ’’ AS lang”;
4 $interface[’table_titre’][’breves’]= ’titre , lang’;
Lorsqu’un objet a déclaré son titre, le générateur d’URL peut créer de belles URL automatiquement (en fonction du jeu d’URL utilisé par le site).
17.36.4 table_date
Cee information permet de déclarer certaines colonnes SQL comme des entrées de type date. Le compilateur de SPIP pourra alors appliquer des critères spéci- fiques à ces types de champs, tel que « age », « age_relatif », « jour_relatif »… Il n’y a qu’un seul champ déclaré de type date possible par table.
1 $interface[’table_date’][’alias’] = ’colonne’;
2 // exemples
3 $interface[’table_date’][’articles’]=’date’;
4 $interface[’table_date’][’evenements’] = ’date_debut’; 180 CHAPITRE 17. LISTE DES PIPELINES
17.36.5 tables_jointures
Ces déclarations permeent au compilateur de déterminer explicitement les join- tures possibles lorsqu’une boucle sur une table demande un champ (balise ou critère) inconnu. Le compilateur sait retrouver de façon implicite certaines jointures (sans les dé- clarer donc) en recherchant la colonne demandée dans les autres tables SQL qu’il connait. Le compilateur ne cherche pas sur toutes les tables, mais uniquement sur celles ayant des colonnes spécifiques communes :
• même nom que la clé primaire, • même nom qu’une colonne déclarée en jointure potentielle dans le des- criptif join des tables principales ou auxiliaires. Dans de nombreux cas, il est utile et préférable de déclarer de façon expli- cite au compilateur les jointures qu’il peut tenter lorsqu’un champ incon- nu sur une table se présente à lui. C’est le but de cee déclaration. L’ordre des déclarations a parfois son importance, puisque dès que le compilateur trouvera le champ recherché dans une des tables possibles à joindre, il liera alors cee table. Même si le champ voulu se trouvait dans la table déclarée ensuite.
1 $interface[’tables_jointures’][’spip_nom’][] = ’autre_table’;
2 $interface[’tables_jointures’][’spip_nom’][’colonne’] = ’autre_table’;
3 // exemples
4 // {id_mot} sur ARTICLES
5 $interface[’tables_jointures’][’spip_articles’][]= ’mots_articles’;
6 $interface[’tables_jointures’][’spip_articles’][]= ’mots’;
7 // jointures evenements (plugin agenda) sur les mots ou articles
8 $interface[’tables_jointures’][’spip_evenements’][]= ’mots’; // a placer avant la jointure sur articles
9 $interface[’tables_jointures’][’spip_evenements’][] = ’articles’;
10 $interface[’tables_jointures’][’spip_evenements’][] = ’mots_evenements’;
11 // jointures articles vers evenements
12 $interface[’tables_jointures’][’spip_articles’][] = ’evenements’;
La plupart du temps, aidé aussi de la description « exceptions_des_jointures » expliqué ensuite, cela suffit pour qu’une boucle SPIP sache calculer les join- tures qui lui sont nécessaires pour afficher les différentes balises deman- dées. Si ce n’est toujours pas suffisant, ne pas oublier que les squelees aussi peuvent indiquer les jointures qu’ils souhaitent avec les boucles et critères (cf. Forcer des jointures (p. 87)). 17.36. DECLARER_TABLES_INTERFACES 181
17.36.6 exceptions_des_jointures
Cee définition permet d’aribuer un alias de colonne créant une jointure sur une table pour récupérer un autre champ, si la jointure est réalisable. C’est un peu le pendant de « exception_des_tables » déclarant une jointure, mais non spécifique à une table donnée. On pourra alors utiliser cet alias comme balise SPIP ou comme critère de boucle. Notons que lorsqu’on utilise ces jointures uniquement comme critère de boucle tel que {titre_mots=xx}, il est préférable d’écrire {mots.titre=xx}, plus gé- nérique et qui ne nécessite pas de déclaration.
1 $interface[’exceptions_des_jointures’][’colonne_alias’] = array(’table’, ’colonne’);
2 // exemples
3 $interface[’exceptions_des_jointures’][’titre_mot’] = array(’spip_mots’, ’titre’);
Un cas particulier existe : un troisième argument peut être donné contenant le nom de la fonction qui va créer la jointure. C’est un usage rare, utilisé par le plugin « Forms & Tables »
1 // cas particulier
2 $interface[’exceptions_des_jointures’][’forms_donnees’][’id_mot’] = array(’spip_forms_donnees_champs’, ’valeur’, ’forms_calculer_critere_externe’);
17.36.7 table_des_traitements
Cee description est très utile ; elle permet de définir des traitements systéma- tiques (filtres) sur certaines balises de SPIP. L’étoile (#BALISE*) désactive ces traitements. Concrètement, pour chaque balise, ou couple balise / boucle, les fonctions in- diquées seront exécutées. %s sera remplacé par le contenu réel que retourne la balise. Deux constantes sont à disposition pour les usages les plus fréquents :
1 // traitements typographiques
2 define(’_TRAITEMENT_TYPO’, ’typo(%s, ”TYPO”, $connect)’);
3 // traitements des raccourcis SPIP ([->artXX],
4 define(’_TRAITEMENT_RACCOURCIS’, ’propre(%s, $connect)’); 182 CHAPITRE 17. LISTE DES PIPELINES
1 $interface[’table_des_traitements’][’BALISE’][]= ’filtre_A(%s)’;
2 $interface[’table_des_traitements’][’BALISE’][]= ’filtre_B(filtre_A(%s))’;
3 $interface[’table_des_traitements’][’BALISE’][]= _TRAITEMENT_TYPO;
4 $interface[’table_des_traitements’][’BALISE’][]= _TRAITEMENT_RACCOURCIS;
5 $interface[’table_des_traitements’][’BALISE’][’boucle’]= _TRAITEMENT_TYPO;
6 // exemples dans SPIP
7 $interface[’table_des_traitements’][’BIO’][]= _TRAITEMENT_RACCOURCIS;
8 $interface[’table_des_traitements’][’CHAPO’][]= _TRAITEMENT_RACCOURCIS;
9 $interface[’table_des_traitements’][’DATE’][]= ’normaliser_date(%s)’;
10 $interface[’table_des_traitements’][’ENV’][]= ’entites_html(%s,true)’;
11 // exemples dans le plugin d’exemple ”chat”
12 $interface[’table_des_traitements’][’RACE’][’chats’] = _TRAITEMENT_TYPO;
13 $interface[’table_des_traitements’][’INFOS’][’chats’] = _TRAITEMENT_RACCOURCIS;
Un exemple très souvent utile est la suppression automatique des numéros sur des titres de rubriques. Cela peut être réalisé comme ceci dans son fichier config/mes_options.php (ou en utilsant ce pipeline dans un plugin évidemment !) :
1 // version simple
2 $GLOBALS[’table_des_traitements’][’TITRE’][]= ’typo(supprimer_numero(%s), ”TYPO”, $connect)’;
3
4 // version complexe (ne pas ecraser la definition existante)
5 if (isset($GLOBALS[’table_des_traitements’][’TITRE’][0])) {
6 ^^I$s = $GLOBALS[’table_des_traitements’][’TITRE’][0];
7 } else {
8 ^^I$s = ’%s’;
9 }
10 $GLOBALS[’table_des_traitements’][’TITRE’][0] = str_replace(’%s’, ’supprimer_numero(%s)’, $s);
17.36.8 Exemple
Prenons l’exemple complexe du plugin Agenda, qui déclare une table spip_evenements, une table de liaison spip_mots_evenenents et une seconde table de liaison spip_evenements_participants. Un alias est posé pour boucler sur les évènements. Des jointures explicites sont déclarées, un champ date et des traitements également. Il y a presque tout ! 17.37. DECLARER_URL_OBJETS 183
1 function agenda_declarer_tables_interfaces($interface){
2 ^^I// ’spip_’ dans l’index de $tables_principales
3 ^^I$interface[’table_des_tables’][’evenements’]=’evenements’;
4
5 ^^I//-- Jointures ------
6 ^^I$interface[’tables_jointures’][’spip_evenements’][]= ’mots’; // a placer avant la jointure sur articles
7 ^^I$interface[’tables_jointures’][’spip_articles’][]= ’evenements’;
8 ^^I$interface[’tables_jointures’][’spip_evenements’][] = ’articles’;
9 ^^I$interface[’tables_jointures’][’spip_mots’][]= ’mots_evenements’;
10 ^^I$interface[’tables_jointures’][’spip_evenements’][] = ’mots_evenements’;
11 ^^I$interface[’tables_jointures’][’spip_evenements’][] = ’evenements_participants’;
12 ^^I$interface[’tables_jointures’][’spip_auteurs’][] = ’evenements_participants’;
13
14 ^^I$interface[’table_des_traitements’][’LIEU’][]= ’propre(%s)’;
15
16 ^^I// permet d’utiliser les criteres racine, meme_parent, id_parent
17 ^^I$interface[’exceptions_des_tables’][’evenements’][’id_parent’]=’id_evenement_source’;
18 ^^I$interface[’exceptions_des_tables’][’evenements’][’id_rubrique’]=array(’spip_articles’, ’id_rubrique’);
19
20 ^^I$interface[’table_date’][’evenements’] = ’date_debut’;
21
22 ^^Ireturn $interface;
23 }
17.37 declarer_url_objets
Ce pipeline permet d’utiliser des URLs standard de SPIP sur les objets indiqués et de calculer la correspondance entre une URL standard et l’objet correspondant. Ces URLs peuvent être de la forme :
• spip.php?objetXX (spip.php ?article12)
• ?objetXX ( ?article12)
• pareil avec .html à la fin. Avec le fichier .htaccess fournit par SPIP et activé, les URL peuvent aussi être : 184 CHAPITRE 17. LISTE DES PIPELINES
• objetXX (article12)
• objetXX.html (article12.html) L’URL calculée lorsqu’on utilise les fonctions de calcul d’URL de SPIP (ba- lise #URL_ ou fonction generer_url_entite) dépend du jeu d’URL sélec- tionné dans la configuration de SPIP. Ce pipeline est appelé dans ecrire/inc/urls.php avec une liste d’objets pré- définie. Il prend et retourne un tableau de la liste des objets pouvant servir d’URL :
1 $url_objets = pipeline(’declarer_url_objets’, array(’article’, ’breve’, ’rubrique’, ’mot’, ’auteur’, ’site’, ’syndic’));
La balise #URL_nom renvoie une URL pour un objet et un identifiant donnée (pas besoin de déclaration pour cela). Ce pipeline est utilisé pour décoder une URL standard et retrouver l’objet et l’identifiant de l’objet sur laquelle elle s’applique. Une fois déclaré un objet « nom », ?nomXX dans l’URL per- met à SPIP de calculer que l’objet est « nom » ; que l’identifiant « id_nom » vaut « XX » et que par conséquent, il doit essayer de charger le squelee nom.html avec l’identifiant trouvé. L’usage de ce pipeline peut aller de pair avec la déclaration de « table_titre » dans le pipeline declarer_tables_interfaces (p. 177). Cela indique sur quelle colonne SQL de l’objet puiser pour créer une URL signifiante.
17.37.1 Exemple
Le plugin « Grappes » utilise ce pipeline permeant de créer des URLs pour cet objet. #URL_GRAPPE crée une URL adaptée à l’objet. SPIP saura alors à quel squelee se référer lorsque cee URL est appelée : grappe.html.
1 function grappes_declarer_url_objets($array){
2 ^^I$array[] = ’grappe’;
3 ^^Ireturn $array;
4 }
Le pipeline d’interface déclare aussi le champ de titre pour des URL signifiantes : 17.38. DEFINIR_SESSION 185
1 function grappes_declarer_tables_interfaces($interface){
2 ^^I// [...]
3 ^^I// Titre pour url
4 ^^I$interface[’table_titre’][’grappes’] = ”titre, ’’ AS lang”;
5 ^^Ireturn $interface;
6 }
17.38 definir_session
Lorsque dans un squelee est utilisée #AUTORISER, #SESSION ou toute balise de- mandant à créer un cache différent par session, un identifiant spécifique est cal- culé avec les informations de session connues du visiteur par la fonction spip_session. Cet identifiant est utilisé pour nommer les fichiers de cache. Lorsqu’aucune in- formation n’est connue du visiteur, l’identifiant retourné est nul.
Le pipeline definir_session permet de compléter les informations servant à créer cet identifiant. Il est donc possible de composer des caches uniques s’ap- puyant sur d’autres paramètres que les données du visiteur. Le pipeline reçoit et retourne une chaîne de caractères. Il est appelé de la sorte dans le fichier ecrire/inc/utils.php :
1 $s = pipeline(’definir_session’,
2 ^^I$GLOBALS[’visiteur_session’]
3 ^^I^^I? serialize($GLOBALS[’visiteur_session’])
4 ^^I^^I. ’_’ . @$_COOKIE[’spip_session’]
5 ^^I: ’’
6 );
Remarque : les informations de session pouvant intervenir très tôt dans le fonc- tionnement de SPIP, il vaut mieux déclarer pour un plugin la fonction du pipeline directement dans un fichier d’options. La déclaration dans le fichier plugin.xml ne nécessite pas de définir la balise XML
1
2
3 ^^I
4 186 CHAPITRE 17. LISTE DES PIPELINES
17.38.1 Exemple
Le plugin « FaceBook Login » définit un cache dépendant aussi de l’authentification à FaceBook si elle est validée :
1 function fblogin_definir_session($flux){
2 ^^I$flux .= (isset($_SESSION[’fb_session’]) ? serialize(isset($_SESSION[’fb_session’])) : ’’);
3 ^^Ireturn $flux;
4 }
Le plugin « Forms & Tables » également définit un cache spécifique lorsque des cookies liés à ses formulaires sont trouvés :
1 function forms_definir_session($session){
2 ^^Iforeach($_COOKIE as $cookie=>$value){
3 ^^I^^Iif (strpos($cookie,’cookie_form_’)!==FALSE)
4 ^^I^^I^^I$session .= ”-$cookie:$value”;
5 ^^I}
6 ^^Ireturn $session;
7 }
On notera que la balise dynamique #FORMS de ce plugin demande à créer un cache par session en meant à true l’option session de la balise :
1 function balise_FORMS ($p) {
2 ^^I$p->descr[’session’] = true;
3
4 ^^Ireturn calculer_balise_dynamique($p, ’FORMS’, array(’id_form’, ’id_article’, ’id_donnee’,’id_donnee_liee’, ’class’));
5 } 17.39. AFFICHAGE_ENTETES_FINAL 187 17.39 affiage_entetes_final
Ce pipeline, appelé sur chaque page publique de SPIP au moment de son affi- chage, reçoit un tableau contenant la liste des entêtes HTTP de la page. Il permet donc de modifier ou de compléter ces entêtes. Il est appelé peu avant le pipeline affichage_final (p. 165) qui lui reçoit uniquement le texte envoyé. Ce pipeline est appelé dans ecrire/public.php prend et retourne un tableau conte- nant les différents entêtes HTTP de page, où les clés du tableau correspondent au nom de l’entête désiré.
1 $page[’entetes’] = pipeline(’affichage_entetes_final’, $page[’entetes’]);
2 // On trouve dans ce tableau par exemple :
3 // $page[’entetes’][’Content-Language’] ...
17.39.1 Exemple
Une utilisation de ce pipeline est de pouvoir gérer les statistiques du site, car en connaissant les entêtes envoyées (donc le type de page) et certains paramètres d’environnement on peut renseigner une table de statistiques de visites (le code réel a été simplifié et provient du plugin « Statistiques ») :
1 // sur les envois html, compter les visites.
2 function stats_affichage_entetes_final($entetes){
3 ^^Iif (($GLOBALS[’meta’][”activer_statistiques”] != ”non”)
4 ^^IAND preg_match(’,^\s*text/html,’, $entetes[’Content-Type’])) {
5 ^^I^^I$stats = charger_fonction(’stats’, ’public’);
6 ^^I^^I$stats();
7 ^^I}
8 ^^Ireturn $entetes;
9 } 188 CHAPITRE 17. LISTE DES PIPELINES
17.39.2 En savoir plus !
La liste des entêtes HTTP existants peut se trouver sur Wikipedia sur la page en
17.40 configurer_liste_metas
Ce pipeline permet de compléter (ou de modifier) les valeurs par défaut des pa- ramètres de configurations de SPIP. Il reçoit en paramètre un tableau de couples « nom / valeur » et le retourne. Ce pipeline est appelé dans ecrire/inc/config.php :
1 return pipeline(’configurer_liste_metas’, array(
2 ^^I’nom_site’ => _T(’info_mon_site_spip’),
3 ^^I’adresse_site’ => preg_replace(”,/$,”, ””, url_de_base()),
4 ^^I’descriptif_site’ => ’’,
5 ^^I//...
6 ));
La fonction config() permet de compléter les paramètres encore absents dans SPIP mais ayant une valeur par défaut définie par le pipeline. Elle est appelée notamment par les formulaires de configurations natifs de SPIP.
1 $config = charger_fonction(’config’, ’inc’);
2 $config();
17.40.1 Exemple
L’extension « Compresseur » l’utilise pour définir les options par défaut du sys- tème de compression des pages. 17.41. LISTER_TABLES_NOEXPORT 189
1 function compresseur_configurer_liste_metas($metas){
2 ^^I$metas[’auto_compress_js’]=’non’;
3 ^^I$metas[’auto_compress_closure’]=’non’;
4 ^^I$metas[’auto_compress_css’]=’non’;
5 ^^Ireturn $metas;
6 }
17.41 lister_tables_noexport
Ce pipeline permet de déclarer les tables SQL qui ne seront pas intégrées dans les sauvegardes SPIP.
Il est appelé dans la fonction lister_tables_noexport du fichier ecrire/base/dump.php. Il prend et retourne un tableau de la liste des tables à ne pas sauvegarder :
1 $EXPORT_tables_noexport = pipeline(’lister_tables_noexport’, $EXPORT_tables_noexport);
Par défaut, certaines tables de SPIP sont déjà exclues : les tables de statistiques, de recherche et les révisions.
17.41.1 Exemple
Le plugin « Géographie » utilise ce pipeline pour décider de ne pas exporter ses tables SQL contenant des données géographiques :
1 function geographie_lister_tables_noexport($liste){
2 ^^I$liste[] = ’spip_geo_communes’;
3 ^^I$liste[] = ’spip_geo_departements’;
4 ^^I$liste[] = ’spip_geo_regions’;
5 ^^I$liste[] = ’spip_geo_pays’;
6 ^^Ireturn $liste;
7 } 190 CHAPITRE 17. LISTE DES PIPELINES 17.42 lister_tables_noimport
Ce pipeline permet d’indiquer les tables SQL à ne pas importer lors d’une restau- ration.
Il est appelé par la fonction lister_tables_noimport de fichier ecrire/base/dump.php. Il prend et retourne un tableau de la liste des tables à ne pas sauvegarder :
1 $IMPORT_tables_noimport = pipeline(’lister_tables_noimport’, $IMPORT_tables_noimport);
17.43 lister_tables_noerase
Ce pipeline permet d’indiquer les tables SQL à ne pas vider juste avant une res- tauration.
Il est appelé par la fonction lister_tables_noerase du fichier ecrire/base/dump.php. Il prend et retourne un tableau de la liste des tables à ne pas purger :
1 $IMPORT_tables_noerase = pipeline(’lister_tables_noerase’, $IMPORT_tables_noerase);
17.44 affier_contenu_objet
Ce pipeline permet de modifier ou compléter le contenu des pages de l’interface privée présentant des objets, tel que la page de visualisation d’un article. Il est appelé dans la vie de chaque objet de d’espace privé, en transmeant le type et d’identifiant de l’objet, dans args, et le code HTML de la vue de l’objet dans data :
1 $fond = pipeline(’afficher_contenu_objet’,
2 ^^Iarray(
3 ^^I’args’=>array(
4 ^^I^^I’type’=>$type,
5 ^^I^^I’id_objet’=>$id_article,
6 ^^I^^I’contexte’=>$contexte),
7 ^^I’data’=> ($fond))); 17.45. DELETE_TABLES 191
17.44.1 Exemple
Le plugin « Métadonnées Photos » ajoute un histogramme des photos et des données EXIF sous le descriptif des images JPG jointes aux objets de la sorte :
1 function photo_infos_pave($args) {
2 ^^Iif ($args[”args”][”type”] == ”case_document”) {
3 ^^I^^I$args[”data”] .= recuperer_fond(”pave_exif”,
4 ^^I^^I^^Iarray(’id_document’ => $args[”args”][”id”]));
5 ^^I}
6 ^^Ireturn $args;
7 }
17.45 delete_tables
Ce pipeline est appelé juste après avoir effectué une action de suppression totale des tables de la base de donnée dans l’interface privée, sur la page ecrire/?exec=admin_effacer. C’est un trigger : un pipeline qui informe simplement d’un évènement, sans pas- ser de paramètre. A ce titre, ce pipeline sera peut être renommé trig_delete_tables dans l’avenir.
1 pipeline(’delete_tables’, ’’);
Il n’y a pas d’application intéressante dans les plugins de SPIP Zone. Il serait possible de l’utiliser pour effectuer des traitements sur une bases de données externe si un site SPIP est réinitialisé de cee manière, ou encore pour envoyer des notifications de l’action à certains destinataires.
17.46 delete_statistiques
Ce pipeline est appelé juste après avoir effectué une action de suppression des statistiques dans l’interface privée, sur la page ecrire/?exec=admin_effacer. 192 CHAPITRE 17. LISTE DES PIPELINES
C’est un trigger : un pipeline qui informe simplement d’un évènement, sans pas- ser de paramètre. A ce titre, ce pipeline sera peut être renommé trig_delete_statistiques dans l’avenir.
1 pipeline(’delete_statistiques’, ’’);
Il n’y a pas encore d’utilisation dans les plugins de SPIP Zone. Ce pipeline doit servir à supprimer des tables SQL de statistiques ajoutées par d’autres plugins.
17.47 taes_generales_cron
Ce pipeline permet de déclarer des fonctions exécutées de manière périodique par SPIP. Il est appelé dans le fichier ecrire/inc/genie.php par la fonction taches_generales, prend et retourne un tableau associatif ayant pour clé le nom de la fonction à exé- cuter et pour valeur la durée en seconde entre chaque exécution.
1 return pipeline(’taches_generales_cron’, $taches_generales);
Lire le chapitre sur le Génie (p. 265) pour plus de renseignements.
17.47.1 Exemple
Un plugin quelconque peut déclarer une fonction de neoyage à exécuter toutes les semaines :
1 function carte_postale_taches_generales_cron($taches){
2 ^^I$taches[’nettoyer_cartes_postales’] = 7*24*3600; // toutes les semaines
3 ^^Ireturn $taches;
4 }
Cee fonction est contenue dans le fichier genie/nettoyer_cartes_postales.php . Elle supprime tous les fi- chiers d’un répertoire donné âgés de plus de 30 jours, grâce à la fonction purger_repertoire : 17.48. COMPTER_CONTRIBUTIONS_AUTEUR 193
1 function genie_nettoyer_cartes_postales_dist($t){
2 ^^I// Purge des cartes postales agees de 30 jours
3 ^^Iinclude_spip(’inc/invalideur’);
4 ^^Ipurger_repertoire(_DIR_IMG . ’cartes_postales/’, array(
5 ^^I^^I’atime’ => (time() - (30 * 24 * 3600)),
6 ^^I));
7 ^^Ireturn 1;
8 }
17.48 compter_contributions_auteur
Ce pipeline permet de compléter, sur la page qui liste les auteurs, le nombre de leurs contributions. Il est appelé comme ceci dans ecrire/inc/formater_auteur.php :
1 $contributions = pipeline(’compter_contributions_auteur’, array(
2 ^^I’args’ => array(’id_auteur’ => $id_auteur, ’row’ => $row),
3 ^^I’data’ => $contributions));
17.48.1 Exemple
Le plugin « Forum » ajoute le nombre de messages qu’a écrit un auteur :
1 function forum_compter_contributions_auteur($flux){
2 ^^I$id_auteur = intval($flux[’args’][’id_auteur’]);
3 ^^Iif ($cpt = sql_countsel(”spip_forum AS F”, ”F.id_auteur=”.intval($flux[’args’][’id_auteur’]))){
4 ^^I^^I// manque ”1 message de forum”
5 ^^I^^I$contributions = ($cpt>1) ? $cpt . ’’. _T(’public:messages_forum’) : ’1 ’ . _T(’public:message’);
6 ^^I^^I$flux[’data’] .= ($flux[’data’]?”, ”:””) . $contributions;
7 ^^I}
8 ^^Ireturn $flux;
9 } 194 CHAPITRE 17. LISTE DES PIPELINES 17.49 trig_supprimer_objets_lies
Ce pipeline est un trigger (il ne retourne rien) appelé au moment de la suppres- sion de certains objets. Il permet de supprimer des informations contenues dans les tables de liaisons en même temps que l’objet supprimé. Il reçoit un tableau des différentes suppressions (contenant le type et l’identifiant de l’objet supprimé).
1 pipeline(’trig_supprimer_objets_lies’, array(
2 ^^I^^Iarray(’type’=>’mot’, ’id’=>$id_mot)
3 ));
Ce pipeline est appelé au moment de la suppression d’un mot-clé et d’un message.
17.49.1 Exemple
Le plugin « Forum » l’utilise pour supprimer les liens avec les messages de forums liés à un mot-clé supprimé ou à un message (de messagerie) supprimé :
1 function forum_trig_supprimer_objets_lies($objets){
2 ^^Iforeach($objets as $objet){
3 ^^I^^Iif ($objet[’type’]==’message’)
4 ^^I^^I^^Isql_delete(”spip_forum”, ”id_message=” . sql_quote($objet[’id’]));
5 ^^I^^Iif ($objet[’type’]==’mot’)
6 ^^I^^I^^Isql_delete(”spip_mots_forum”, ”id_mot=” . intval($objet[’id’]));
7 ^^I}
8 ^^Ireturn $objets;
9 }
17.50 formulaire_verifier
Ce pipeline est appelé dans ecrire/public/aiguiller.php au moment de la vérifi- cation des données soumises d’un formulaire CVT. Il permet de compléter le tableau d’erreurs renvoyé par la fonction verifier (p. 287) du formulaire en ques- tion. 17.50. FORMULAIRE_VERIFIER 195
Il reçoit les mêmes arguments que le pipeline formulaire_charger (p. 155), à sa- voir le nom du formulaire ainsi que les paramètres transmis dans les fonctions charger, verifier et traiter. Il retourne le tableau des erreurs.
1 $verifier = charger_fonction(”verifier”,”formulaires/$form/”,true);
2 $post[”erreurs_$form”] = pipeline(’formulaire_verifier’, array(
3 ^^I’args’ => array(
4 ^^I^^I’form’=>$form,
5 ^^I^^I’args’=>$args),
6 ^^I’data’=>$verifier
7 ^^I^^I? call_user_func_array($verifier, $args)
8 ^^I^^I: array()));
17.50.1 Exemple
Le plugin « OpenID » se sert de ce pipeline pour vérifier, lorsqu’un auteur édite ses informations, que l’URL OpenID indiquée est correcte et dans le cas contraire indique une erreur sur le champ en question.
1 function openid_formulaire_verifier($flux){
2 ^^Iif ($flux[’args’][’form’] == ’editer_auteur’){
3 ^^I^^Iif ($openid = _request(’openid’)){
4 ^^I^^I^^Iinclude_spip(’inc/openid’);
5 ^^I^^I^^I$openid = nettoyer_openid($openid);
6 ^^I^^I^^Iif (!verifier_openid($openid))
7 ^^I^^I^^I^^I$flux[’data’][’openid’] = _T(’openid:erreur_openid’);
8 ^^I^^I}
9 ^^I}
10 ^^I// [...]
11 ^^Ireturn $flux;
12 } 196 CHAPITRE 17. LISTE DES PIPELINES 17.51 insert_head_css
Le pipeline insert_head_css permet à des plugins d’insérer les fichiers CSS qui leur sont nécessaires, au moment de l’appel de la balise #INSERT_HEAD_CSS si présente, sinon en début du résultat de #INSERT_HEAD. Cela permet à un sque- lee d’indiquer l’emplacement des CSS supplémentaires chargées. Il est appelé simplement par :
1 return pipeline(’insert_head_css’, ’’);
17.51.1 Exemple
L’extension « Porte Plume » l’utilise (en simplifiant) pour ajouter deux fichiers CSS, le second étant d’ailleurs un squelee SPIP :
1 function porte_plume_insert_head_css($flux) {
2 ^^I$css = find_in_path(’css/barre_outils.css’);
3 ^^I$css_icones = generer_url_public(’barre_outils_icones.css’);
4 ^^I$flux .= ”\n”
5 ^^I^^I. ”\n”;
6 ^^Ireturn $flux;
7 }
17.52 formulaire_traiter
Ce pipeline est appelé dans ecrire/public/aiguiller.php après les traitements (p. 288) d’un formulaire CVT. Il permet de compléter le tableau de réponse ou d’ef- fectuer des traitements supplémentaires. Il reçoit les mêmes arguments que les pipelines formulaire_charger (p. 155) ou formulaire_verifier (p. 194). Il retourne le tableau d’informations résultant du traitement (message d’erreur, de réussite, redirection, formulaire éditable de nou- veau…). 17.52. FORMULAIRE_TRAITER 197
1 $rev = pipeline(
2 ^^I’formulaire_traiter’,
3 ^^Iarray(
4 ^^I^^I’args’ => array(’form’=>$form, ’args’=>$args),
5 ^^I^^I’data’ => $rev)
6 );
17.52.1 Exemple
Le plugin « Licence » qui offre la possibilité d’aribuer une licence d’utilisation aux articles l’utilise pour enregistrer la valeur de la licence par défaut enregistrée dans la configuration, au moment de la création d’un nouvel article :
1 function licence_formulaire_traiter($flux){
2 ^^I// si creation d’un nouvel article lui attribuer la licence par defaut de la config
3 ^^Iif ($flux[’args’][’form’] == ’editer_article’ AND $flux[’args’][’args’][0] == ’new’) {
4 ^^I^^I$id_article = $flux[’data’][’id_article’];
5 ^^I^^I$licence_defaut = lire_config(’licence/licence_defaut’);
6 ^^I^^Isql_updateq(’spip_articles’, array(’id_licence’ => $licence_defaut), ’id_article=’ . intval($id_article));
7 ^^I}
8 ^^Ireturn $flux;
9 }
Notes :
• la fonction PHP lire_config() appartient au plugin de configuration « CFG ».
• en SPIP 2.1, il serait plus pertinent d’utiliser le pipeline pre_insertion (p. 158) pour ce cet exemple précis. 198 CHAPITRE 17. LISTE DES PIPELINES 17.53 alertes_auteur
SPIP sait envoyer des messages d’alerte pour différentes occasions plus ou moins urgentes :
• Crash de la base de données
• Crash d’un plugin
• Erreur d’activation d’un plugin
• Avertissement pour prévenir d’un message dans la messagerie Ce pipeline, appelé dans ecrire/inc/commencer_page.php par la fonction alertes_auteur(), permet de compléter le tableau contenant ces alertes.
1 $alertes = pipeline(’alertes_auteur’, array(
2 ^^I^^I ’args’ => array(
3 ^^I^^I^^I ’id_auteur’ => $id_auteur,
4 ^^I^^I^^I’exec’ => _request(’exec’),
5 ^^I^^I),
6 ^^I^^I ’data’ => $alertes
7 ^^I)
8 );
Il reçoit un tableau en paramètre.
• data : contient un tableau de texte des différentes alertes,
• args contient un tableau avec :
– id_auteur est l’auteur actuellement connecté, – exec est le nom de la page affichée.
17.53.1 Exemple
S’il existait un plugin « Aention aux bananes » qui indiquerait aux gens qu’ils risquent de marcher sur une banane et se casser la figure, alors il pourrait faire : 17.54. PRE_TYPO 199
1 function bananes_alertes_auteur($flux){
2 ^^I$alertes = $flux[’data’];
3
4 ^^I// S’il y a une banane devant cet auteur
5 ^^Iif (tester_banane($flux[’args’][’id_auteur’])) {
6 ^^I^^I// On ajoute une alerte
7 ^^I^^I$alertes[] = ”Attention ! Une banane !”;
8 ^^I}
9
10 ^^I// On retourne le tableau des alertes
11 ^^Ireturn $alertes;
12 }
Heureusement que le plugin était là.
17.54 pre_typo
Le pipeline pre_typo permet de modifier le texte avant d’effectuer les traite- ments typographiques prévus par SPIP. Il est appelé par la fonction corriger_typo() de ecrire/inc/texte.php, fonction qui est appelée lors de l’utilisation des fonctions propre() ou typo().
1 $letexte = pipeline(’pre_typo’, $letexte);
Les modifications proposées doivent s’occuper uniquement de traitement pour des éléments qui pourront être affichés sur une seule ligne (inline). Pour des trai- tements qui modifient ou créent des blocs ou paragraphes, il faudra utiliser le pipeline pre_propre.
17.54.1 Exemple
Le plugin « Enluminures Typographiques » modifie automatiquement quelques écritures de caractères, par exemple pour transformer « (c) » en « © » : 200 CHAPITRE 17. LISTE DES PIPELINES
1 function typoenluminee_pre_typo($texte) {
2 ^^I// ...
3 ^^I$chercher_raccourcis = array(
4 ^^I^^I// ...
5 ^^I^^I/* 19 */ ^^I”/\(c\)/Si”,
6 ^^I^^I/* 20 */ ^^I”/\(r\)/Si”,
7 ^^I^^I/* 21 */ ^^I”/\(tm\)/Si”,
8 ^^I^^I/* 22 */ ^^I”/\.\.\./S”,
9 ^^I);
10
11 ^^I$remplacer_raccourcis = array(
12 ^^I^^I// ...
13 ^^I^^I/* 19 */ ^^I”©”,
14 ^^I^^I/* 20 */ ^^I”®”,
15 ^^I^^I/* 21 */ ^^I”™”,
16 ^^I^^I/* 22 */ ^^I”…”,
17 ^^I);
18 ^^I// ...
19 ^^I$texte = preg_replace($chercher_raccourcis, $remplacer_raccourcis, $texte);
20 ^^I// ...
21 ^^Ireturn $texte;
22 }
17.55 post_typo
Le pipeline post_typo permet de modifier le texte après que SPIP ait effectué les traitements typographiques prévus, et donc après le pipeline pre_typo (p. 199) également. Il est appelé par la fonction corriger_typo() de ecrire/inc/texte.php, fonction qui est appelée lors de l’utilisation des fonctions propre() ou typo().
1 $letexte = pipeline(’post_typo’, $letexte); 17.56. OBJET_COMPTE_ENFANTS 201
17.55.1 Exemple
Le plugin « Typo Guillemets » remplace dans un texte les guillemets ” par l’équi- valent adapté à la langue comme « et » pour le français. Il analyse pour cela le texte une fois les raccourcis typographiques appliqués comme cela :
1 function typo_guillemets_post_typo($texte) {
2 ^^I// ...
3 ^^Iswitch ($GLOBALS[’spip_lang’]) {
4 ^^I^^Icase ’fr’:
5 ^^I^^I^^I$guilles=”« $2 »”; //LRTEUIN
6 ^^I^^I^^Ibreak;
7 ^^I^^I// ...
8 ^^I}
9
10 ^^I// on echappe les ” dans les tags ;
11 ^^I// attention ici \01 est le caractere chr(1), et \$0 represente le tag
12 ^^I$texte = preg_replace(’,<[^>]*”[^>]*(>|$),msSe’, ”str_replace(’\”’,’\01’, \”\$0\”)”, $texte);
13
14 ^^I// on corrige les guill restants, qui sont par definition hors des tags
15 ^^I// Un guill n’est pas pris s’il suit un caractere autre que espace, ou
16 ^^I// s’il est suivi par un caractere de mot (lettre, chiffre)
17 ^^I$texte = preg_replace(’/(^|\s)”\s?([^”]*?)\s?”(\W|$)/S’, ’$1’.$guilles.’$3’, $texte);
18
19 ^^I// et on remet les guill des tags
20 ^^Ireturn str_replace(”\01”, ’”’, $texte);
21 }
17.56 objet_compte_enfants
Ce pipeline permet de compléter ou de modifier le comptage des enfants d’un objet. Il est appelé comme ceci dans le fichier ecrire/inc/rubriques.php :
1 // On passe le tableau des comptes dans un pipeline pour que les plugins puissent ajouter (ou retirer) des enfants 202 CHAPITRE 17. LISTE DES PIPELINES
2 $compte = pipeline(’objet_compte_enfants’,
3 ^^Iarray(
4 ^^I^^I’args’ => array(
5 ^^I^^I^^I’objet’ => ’rubrique’,
6 ^^I^^I^^I’id_objet’ => $id_rubrique,
7 ^^I^^I^^I’statut’ => ’publie’,
8 ^^I^^I^^I’date’ => $date
9 ^^I^^I),
10 ^^I^^I’data’ => $compte
11 ^^I)
12 );
Il reçoit comme arguments l’objet dont on veut compter les enfants grâce à objet et id_objet. Il peut aussi recevoir la date ainsi que le statut des enfants que l’on veut compter. Dans l’appel précédent, on demande donc à compter les enfants publiés d’une rubrique donnée.
Le contenu data du pipeline est un tableau associatif, dans lequel la clé est le type d’un objet au pluriel (par exemple : « articles »), et la valeur est un nombre entier, correspondant au nombre d’enfants de ce type.
17.56.1 Exemple
Le plugin « Polyhiérarchie » ajoute aux rubriques le comptage des enfants indi- rects :
1 function polyhier_objet_compte_enfants($flux) {
2
3 ^^Iif ($flux[’args’][’objet’]==’rubrique’){
4 ^^I^^I$statut = (isset($flux[’args’][’statut’])?” AND A.statut=”.sql_quote($flux[’args’][’statut’]):””);
5 ^^I^^I$postdates = ($GLOBALS[’meta’][”post_dates”] == ”non”) ?
6 ^^I^^I^^I” AND A.date <= ”.sql_quote(date(’Y-m-d H:i:s’)) : ’’;
7
8 ^^I^^I$flux[’data’][’articles_indirects’]+= sql_countsel(
9 ^^I^^I^^I^^I^^I^^I”spip_rubriques_liens as RL join spip_articles as A ON (RL.objet=’article’ AND RL.id_objet=A.id_article)”,
10 ^^I^^I^^I^^I^^I^^I’RL.id_parent=’.$flux[’args’][’id_objet’].$statut.$postdates); 17.57. AFFICHER_NOMBRE_OBJETS_ASSOCIES_A 203
11
12 ^^I^^I$statut = (isset($flux[’args’][’statut’])?” AND R.statut=”.sql_quote($flux[’args’][’statut’]):””);
13 ^^I^^I$flux[’data’][’rubriques_indirectes’]+= sql_countsel(
14 ^^I^^I^^I^^I^^I^^I”spip_rubriques_liens as RL join spip_rubriques as R ON (RL.objet=’rubrique’ AND RL.id_objet=R.id_rubrique)”,
15 ^^I^^I^^I^^I^^I^^I’RL.id_parent=’.$flux[’args’][’id_objet’].$statut);
16 ^^I}
17 ^^Ireturn $flux;
18 }
17.57 affier_nombre_objets_associes_a
Le pipeline afficher_nombre_objets_associes_a est appelé pour afficher des informations de nombre d’éléments lié à un objet éditorial. Il permet ainsi de compléter le nombre d’éléments liés à un mot clé donné lorsqu’il est appelé sur la page des groupes de mots ainsi :
1 $texte_lie = pipeline(
2 ^^I’afficher_nombre_objets_associes_a’,
3 ^^Iarray(
4 ^^I^^I’args’=>array(
5 ^^I^^I^^I’objet’=>’mot’,
6 ^^I^^I^^I’id_objet’=>$id_mot),
7 ^^I^^I’data’=>$texte_lie));
Est transmis au pipeline le type d’objet et son identifiant dont on souhaite comp- ter les liaisons associées. La clé data est un tableau dont les valeurs seront as- semblées avec une virgule au moment de l’affichage.
17.57.1 Exemple
Le plugin « Agenda » utilise ce pipeline pour ajouter le nombre d’évènements liés à un mot clé de la sorte : 204 CHAPITRE 17. LISTE DES PIPELINES
1 function agenda_afficher_nombre_objets_associes_a($flux){
2 ^^Iif ($flux[’args’][’objet’] == ’mot’
3 ^^I AND $id_mot = $flux[’args’][’id_objet’]){
4 ^^I^^I$aff_articles = sql_in(’A.statut’,($GLOBALS[’connect_statut’] == ”0minirezo”) ? array(’prepa’,’prop’,’publie’) : array(’prop’,’publie’));
5 ^^I^^I$nb = sql_countsel(”spip_mots_evenements AS L LEFT JOIN spip_evenements AS E ON E.id_evenement=L.id_evenement LEFT JOIN spip_articles AS A ON E.id_article=A.id_article”, ”L.id_mot=”.intval($id_mot).” AND $aff_articles”);
6 ^^I^^Iif ($nb)
7 ^^I^^I^^I$flux[’data’][] = singulier_ou_pluriel($nb, ”agenda:info_un_evenement”, ”agenda:info_nombre_evenements”);
8 ^^I}
9 ^^Ireturn $flux;
10 }
17.58 … et les autres
Il reste un certain nombre de pipelines à documenter. Voici leur noms :
1. affiche_formulaire_login
2. arbo_creer_chaine_url
3. agenda_rendu_evenement
4. base_admin_repair
5. calculer_rubriques
6. exec_init
7. formulaire_admin
8. mots_indexation
9. neoyer_raccourcis_typo
10. notifications
11. page_indisponible
12. post_boucle
13. post_image_filtrer 17.58. … ET LES AUTRES 205
14. pre_propre
15. post_propre
16. pre_edition
17. post_edition
18. pre_syndication
19. post_syndication
20. pre_indexation
21. propres_creer_chaine_url
22. requete_dico
23. trig_calculer_prochain_postdate
24. trig_propager_les_secteurs 206 CHAPITRE 17. LISTE DES PIPELINES 207
Chapitre 18
Balises
Explications, fonctionnement, création de balises statiques, dynamiques ou gé- nériques de SPIP.
18.1 Les balises dynamiques
Les balises dynamiques sont des balises qui sont calculées à chaque affichage de la page, contrairement aux balises statiques qui sont calculées uniquement lors du calcul de la page. Ces balises dynamiques stockent donc dans le cache généré une portion de PHP qui sera exécuté à l’affichage. En principe, elles servent essentiellement pour af- ficher des formulaires. Un fichier de balise dynamique peut comporter jusqu’à 3 fonctions essentielles : balise_NOM_dist(), balise_NOM_stat(), balise_NOM_dyn().
18.2 Fonction balise_NOM_dist
La première fonction d’une balise dynamique est la même fonction utilisée pour les balises statiques, c’est à dire une fonction du nom de la balise : balise_NOM_dist(). Cee fonction, au lieu d’insérer un code statique va appeler une fonction géné- rant un code dynamique : calculer_balise_dynamique(). 208 CHAPITRE 18. BALISES
En général, le contenu de la fonction se résume à l’appel du calcul dynamique, comme pour cet exemple de la balise #LOGIN_PRIVE :
1 function balise_LOGIN_PRIVE ($p) {
2 ^^Ireturn calculer_balise_dynamique($p, ’LOGIN_PRIVE’, array(’url’));
3 }
La fonction de balise reçoit la variable $p, contenant les informations issues de l’analyse du squelee concernant la balise en question (arguments, filtres, à quelle boucle elle appartient, etc.).
La fonction calculer_balise_dynamique prend 3 à 4 arguments :
• le descriptif $p • le nom de la balise dynamique à exécuter (en général, le même nom que la balise !) • un tableau d’argument à récupérer du contexte de la page. Ici la balise dy- namique demande à récupérer un paramètre url issu du contexte (boucle la plus proche ou environnement de compilation du squelee). Si l’on n’a pas de paramètre à récupérer du contexte, il faut donner un array() vide • optionnel, le 4e argument permet d’envoyer un tableau d’éléments qui se- ra transmis à la fonction suivante (balise_NOM_stat), complétant alors le tableau $context_compil. On peut donc calculer des éléments dans la fonction balise_NOM_dist() et les transmere.
18.3 Fonction balise_NOM_stat()
Si elle existe, la fonction balise_NOM_stat() va permere de calculer les ar- guments à transmere à la fonction suivante (_dyn()). En son absence, seuls les arguments indiqués dans la fonction calculer_balise_dynamique() sont transmis (dans l’ordre du tableau). La fonction stat, va permere de transmere en plus des paramètres issus d’arguments ou des filtres transmis à la balise.
Le fonction reçoit 2 arguments : $args et $context_compil.
• $args contient les arguments imposés par la fonction calculer_balise_dynamique(), cumulés avec les arguments transmis à la balise. 18.3. FONCTION BALISE_NOM_STAT() 209
• $context_compil est un tableau d’informations sur la compilation effec- tuée, comportant 5 entrées (nom du squelee, nom du fichier compilé, nom de la boucle éventuelle où figure la balise, numéro de ligne, langue), suivies éventuellement des éléments du tableau optionnel fournis par la fonction principale de la balise dynamique (4e argument de la fonction calculer_balise_dynamique).
18.3.1 Exemple
Reprenons l’exemple de #LOGIN_PUBLIC : elle fonctionne avec 1 ou 2 arguments : le premier est l’URL de redirection après s’être logé, le second est le login par défaut de la personne à loger. Les deux sont optionnels. On peut donc passer à la balise un argument de redirection : #LOGIN_PUBLIC{#SELF} ou #LOGIN_PUBLIC{#URL_ARTICLE{8}}, mais en absence d’argument, on souhaite que la redirection soit faite sur un paramètre d’environnement url s’il existe. On avait demandé à récupérer cet argument, il se trouve dans $args[0]. $args[1] lui contient le contenu du premier argument donné à la balise (il s’ajoute dans le tableau $args après la liste des arguments automatiquement récupérés). Ceci donne :
1 function balise_LOGIN_PUBLIC_stat($args, $context_compil) {
2 ^^Ireturn array(
3 ^^I^^Iisset($args[1])
4 ^^I^^I^^I? $args[1]
5 ^^I^^I^^I: $args[0],
6 ^^I^^I(isset($args[2])
7 ^^I^^I^^I? $args[2]
8 ^^I^^I^^I: ’’)
9 ^^I);
10 }
Si $args[1] est présent on le transmet, sinon $args[0]. De même si $args[2] est présent, on le transmet, sinon ”.
La fonction _dyn() recevra ces 2 arguments transmis : 210 CHAPITRE 18. BALISES
1 function balise_LOGIN_PUBLIC_dyn($url, $login) {
2 ...
3 }
18.4 Fonction balise_NOM_dyn()
Cee fonction permet d’exécuter les traitements à effectuer si un formulaire a été soumis. La fonction peut retourner une chaîne de caractère (qui sera affichée sur la page demandée) ou un tableau de paramètres qui indique le nom du squelee à récupérer et le contexte de compilation.
18.4.1 Les traitements
Pour 2 raisons je n’en parlerai pas :
• je n’ai toujours pas compris comment ça fonctionne,
• ce n’est plus très utile depuis que SPIP intègre un mécanisme plus simple appelé « formulaires CVT » (Charger, Vérifier, Traiter) qui s’appuie aussi sur cee fonction, mais de façon transparente.
18.4.2 L’affiage
Ce que retourne la fonction est alors affiché sur la page. Un tableau indique un squelee à appeler. Il se présente sous cee forme :
1 return array(”adresse_du_squelette”,
2 ^^I3600, // duree du cache
3 ^^Iarray( // contexte
4 ^^I^^I’id_article’ => $id_article,
5 ^^I)
6 ); 18.5. BALISES GÉNÉRIQUES 211 18.5 Balises génériques
Un autre mécanisme malin de SPIP est la gestion des balises qu’on peut qualifier de génériques. En fait, il est possible d’utiliser une seule déclaration de balise pour tout un groupe de balises préfixées d’un nom identique.
Ainsi une balise #PREFIXE_NOM peut utiliser un fichier balise/prefixe_.php et déclarer une fonction balise_PREFIXE__dist() qui sera alors utilisée si aucune fonction balise_PREFIXE_NOM_dist($p) est présente.
La fonction générique, qui reçoit les aributs de la balise dans la variable $p, peut utiliser $p->nom_champ pour obtenir le nom de la balise demandée (ici ”PRE- FIXE_NOM”). En analysant ce nom, on peut donc effectuer des actions adéquates.
18.5.1 Exemple
Cet exemple est utilisé par les balises génériques #FORMULAIRE_NOM, qui en plus sont des balises dynamiques (fichier ecrire/balise/formulaire_.php).
1 function balise_FORMULAIRE__dist($p) {
2 ^^Ipreg_match(”,^FORMULAIRE_(.*)?$,”, $p->nom_champ, $regs);
3 ^^I$form = $regs[1];
4 ^^Ireturn calculer_balise_dynamique($p,”FORMULAIRE_$form”,array());
5 }
18.6 Récupérer objet et id_objet
Nous allons voir comment récupérer le type (objet) et l’identifiant d’une boucle pour s’en servir dans les calculs d’une balise.
18.6.1 Balise statique
Avec les paramètres de balise $p, il est très simple de récupérer objet et id_objet : 212 CHAPITRE 18. BALISES
1 function balise_DEMO($p){
2 ^^I// on prend nom de la cle primaire de l’objet pour calculer sa valeur
3 ^^I$_id_objet = $p->boucles[$p->id_boucle]->primary;
4 ^^I$id_objet = champ_sql($_id_objet, $p);
5 ^^I$objet = $p->boucles[$p->id_boucle]->id_table;
6 ^^I$p->code = ”calculer_balise_DEMO(’$objet’, $id_objet)”;
7 ^^Ireturn $p;
8 }
9 function calculer_balise_DEMO($objet, $id_objet){
10 ^^I$objet = objet_type($objet);
11 ^^Ireturn ”Objet : $objet, id_objet : $id_objet”;
12 }
Observons les deux fonctions. La première récupère dans la description de la ba- lise le nom de sa boucle parente, le nom de la clé primaire, et demande à récupérer via la fonction champ_sql() la valeur de la clé primaire. Aention : ce que l’on récupère dans la variable $id_objet est un code qui doit être évalué en PHP (ce n’est pas une valeur numérique encore). Une fois ces paramètres récupérés, on demande d’ajouter un code PHP à éva- luer dans le code généré par la compilation du squelee (ce code sera mis en cache). C’est ce qu’on ajoute dans $p->code. Ce code là sera évalué par la suite au moment de la création du cache de la page appelée.
La fonction calculer_balise_DEMO() reçoit alors les deux arguments souhai- tés et retourne un texte qui les affiche sur la page.
1
2 ^^I#DEMO
3
4 ^^I
5
6 ^^I#DEMO
7
Ce squelee permet alors de voir le résultat, la balise #DEMO reçoit des informa- tions différentes en fonction du contexte dans lequel elle se trouve :
1 Objet : article, id_objet : 128
2 Objet : article, id_objet : 7 18.6. RÉCUPÉRER OBJET ET ID_OBJET 213
3 ----
4 Objet : rubrique, id_objet : 1
5 Objet : rubrique, id_objet : 2
18.6.2 Balise dynamique
Dans le cas d’une balise dynamique, son fonctionnement même empêche de récu- pérer facilement le type et l’identifiant de la boucle dans laquelle elle est inscrite. Lorsqu’on a néanmoins besoin de cela, par exemple pour créer des formulaires CVT qui adaptent leurs traitements en fonction du type de boucle, il faut envoyer à la fonction _dyn() (et par conséquent aux fonctions charger, vérifier et traiter de CVT) le type (objet) et l’identifiant de la boucle en cours.
L’appel à calculer_balise_dynamique() permet de récupérer des éléments du contexte de compilation. Si l’on demande à récupérer ’id_article’, on l’obtiendra bien dans une boucle ARTICLES, mais pas dans une boucle RUBRIQUES. En étant plus précis, lorsqu’on demande une valeur ’id_article’, SPIP fait comme s’il ré- cupérait le résultat d’une balise #ID_ARTICLE, il cherche donc la valeur dans la boucle la plus proche, sinon dans le contexte, et aussi en fonction des balises qui ont été déclarées spécifiquement.
On peut demander à calculer id_objet facilement, mais objet va nécessiter de passer par une balise renvoyant la valeur de l’objet. Cee balise n’existant pas par défaut dans SPIP 2.0, il faut en créer une (DEMODYN_OBJET), ce qui donne :
1 function balise_DEMODYN($p){
2 ^^I// cle primaire
3 ^^I$_id_objet = $p->boucles[$p->id_boucle]->primary;
4 ^^Ireturn calculer_balise_dynamique(
5 ^^I^^I$p, ’DEMODYN’, array(’DEMODYN_OBJET’, $_id_objet)
6 ^^I);
7 }
8
9 function balise_DEMODYN_OBJET($p) {
10 ^^I$objet = $p->boucles[$p->id_boucle]->id_table;
11 ^^I$p->code = $objet ? objet_type($objet) : ”balise_hors_boucle”;
12 ^^Ireturn $p;
13 }
14 214 CHAPITRE 18. BALISES
15 function balise_DEMODYN_dyn($objet, $id_objet){
16 ^^Ireturn ”Objet : $objet, id_objet : $id_objet”;
17 } 215
Chapitre 19
Créer des pages dans l’espace privé
Les pages de l’espace privé peuvent être complétée en créant de nouveaux fichiers pour y accéder. Il y a deux manières différentes de mere en place ces pages :
• Dans le répertoire exec, on peut les écrire en PHP.
• Dans le répertoire prive/exec, on peut les écrire en squelees SPIP.
19.1 Contenu d’un fiier exec (squelette)
L’appel dans l’espace privé d’une page ?exec=nom charge automatiquement un squelee placé dans prive/exec/nom.html. Dans la majorité des cas, il est recommandé d’utiliser cee méthode plutôt qu’un fichier PHP. L’objectif est que l’espace privé de SPIP soit lui aussi écrit en sque- lee, donc plus facilement personnalisable. Il est ainsi possible d’utiliser des boucles, inclusions, balises, autorisations, comme dans tout squelee SPIP. Exemple de squelette d’une page privée vide :
1
2
- Une liste de pages constituant un chemin
3 ^^I
4
5
6 216 CHAPITRE 19. CRÉER DES PAGES DANS L’ESPACE PRIVÉ
7
Une page privée directement en squelette
8
Du contenu dans la page
9
10
11
12 Une information dans une colonne de navigation.
13
14
15
16
17 Du contenu en plus dans la colonne extra.
18
Les encadrements , et
5
7 ^^I^^I<:formidable:formulaires_tous:>
8 ^^I
10 ^^I^^I
11 ^^I^^I^^I>
12 ^^I^^I^^I
13 ^^I^^I^^I^^I|parametre_url{id_formulaire, #ID_FORMULAIRE})]”>#TITRE
14 ^^I^^I
15 ^^I
6 ^^I
9 ^^I
16
17
18
19
25
26 ^^I<:formidable:voir_reponses:>
27 ^^I
#TITRE
28 ^^I
29
30
31 32 ^^I {titre=<:formidable:reponses_liste_publie:>}{ajax} /> 33 34 35 36 ^^I 37 ^^I^^I<:formidable:voir_numero:> 38 ^^I^^I #ID_FORMULAIRE 39 ^^I 40 ^^I 46 ^^I 53
54
55
56
Remarques :
• L’ensemble est entouré d’une boucle testant l’existence du formulaire : s’il n’existe pas le squelee ne renverra rien et produira une erreur.
• De la même façon il est entouré d’un test avec #AUTORISER (p. 228) pour vérifier que la personne a le droit de voir les réponses. On utilise ici la boucle CONDITION du plugin « Bonux », afin de pouvoir continuer à écrire des boucles SPIP à l’intérieur de la condition.
• Le bloc affiche un chemin pertinent parmi les pages privées du plugin.
19.2 Contenu d’un fiier exec (PHP)
En l’absence de squelee SPIP prive/exec/nom.html, l’appel dans l’espace pri- vé d’une page ?exec=nom charge une fonction exec_nom_dist() dans un fichier exec/nom.php. 19.2. CONTENU D’UN FICHIER EXEC (PHP) 219
Ces fonctions sont pour la plupart découpées de la même façon : l’appel à un début de page, la déclaration d’une colonne gauche, d’une colonne droite, d’un centre. Des pipelines sont présents pour que des plugins puissent ajouter des informations dans ces blocs. Exemple de page vide « nom »
1
2 if (!defined(”_ECRIRE_INC_VERSION”)) return;
3
4 include_spip(’inc/presentation’);
5
6 function exec_nom_dist(){
7
8 ^^I// si pas autorise : message d’erreur
9 ^^Iif (!autoriser(’voir’, ’nom’)) {
10 ^^I^^Iinclude_spip(’inc/minipres’);
11 ^^I^^Iecho minipres();
12 ^^I^^Iexit;
13 ^^I}
14
15 ^^I// pipeline d’initialisation
16 ^^Ipipeline(’exec_init’, array(’args’=>array(’exec’=>’nom’),’data’=>’’));
17
18 ^^I// entetes
19 ^^I$commencer_page = charger_fonction(’commencer_page’, ’inc’);
20 ^^I// titre, partie, sous_partie (pour le menu)
21 ^^Iecho $commencer_page(_T(’plugin:titre_nom’), ”editer”, ”editer”);
22
23 ^^I// titre
24 ^^Iecho ”
\n”; // outch ! aie aie aie ! au secours !
25 ^^Iecho gros_titre(_T(’plugin:titre_nom’),’’, false);
26
27 ^^I// colonne gauche
28 ^^Iecho debut_gauche(’’, true);
29 ^^Iecho pipeline(’affiche_gauche’, array(’args’=>array(’exec’=>’nom’),’data’=>’’));
30
31 ^^I// colonne droite
32 ^^Iecho creer_colonne_droite(’’, true);
33 ^^Iecho pipeline(’affiche_droite’, array(’args’=>array(’exec’=>’nom’),’data’=>’’));
34 220 CHAPITRE 19. CRÉER DES PAGES DANS L’ESPACE PRIVÉ
35 ^^I// centre
36 ^^Iecho debut_droite(’’, true);
37
38 ^^I// contenu
39 ^^I// ...
40 ^^Iecho ”afficher ici ce que l’on souhaite !”;
41 ^^I// ...
42 ^^I// fin contenu
43
44 ^^Iecho pipeline(’affiche_milieu’, array(’args’=>array(’exec’=>’nom’),’data’=>’’));
45
46 ^^Iecho fin_gauche(), fin_page();
47 }
48 ?>
19.3 Boite d’information
Pour ajouter une description de la page, ou une description de l’objet/id_objet en cours de lecture, un type d’encart est prévu : « boite_infos » Il est souvent utilisé de la sorte, en ajoutant une fonction dans la colonne gauche :
1 // colonne gauche
2 echo debut_gauche(’’, true);
3 echo cadre_nom_infos();
4 echo pipeline(’affiche_gauche’, array(’args’=>array(’exec’=>’nom’),’data’=>’’));
Cee fonction appelle le pipeline et retourne son contenu dans une boite :
1 // afficher les informations de la page
2 function cadre_champs_extras_infos() {
3 ^^I$boite = pipeline (’boite_infos’, array(’data’ => ’’,
4 ^^I^^I’args’ => array(
5 ^^I^^I^^I’type’=>’nom’,
6 ^^I^^I^^I// eventuellement l’id de l’objet et la ligne SQL
7 ^^I^^I^^I// $row = sql_fetsel(’*’, ’spip_nom’, ’id_nom=’.sql_quote($id_nom));
8 ^^I^^I^^I’id’ => $id_nom, 19.3. BOITE D’INFORMATION 221
9 ^^I^^I^^I’row’ => $row,
10 ^^I^^I)
11 ^^I));
12 ^^Iif ($boite)
13 ^^I^^Ireturn debut_boite_info(true) . $boite . fin_boite_info(true);
14 }
Le pipeline charge automatiquement un squelee (avec le contexte fourni par le tableau args) homonyme au paramètre « type », dans le répertoire prive/infos/ soit prive/infos/nom.html. Il faut donc le créer avec le contenu souhaité. 222 CHAPITRE 19. CRÉER DES PAGES DANS L’ESPACE PRIVÉ Cinquième partie
Fonctionnalités
223
225
Ce chapitre développe quelques fonctionnements de SPIP en détail ; autorisa- tions, actions, authentifications, cache, compilateur… 226 227
Chapitre 20
Autorisations
Deux éléments essentiels permeent de gérer les accès aux actions et aux affi- chages des pages de SPIP : les autorisations, avec la fonction autoriser(), et les actions sécurisées par auteur, avec la fonction securiser_action().
20.1 La librairie « autoriser »
SPIP dispose d’une fonction extensible autoriser() permeant de vérifier des autorisations. Cee fonction admet 5 arguments. Seul le premier est indispen- sable, les autres étant optionnels.
1 autoriser($faire, $type, $id, $qui, $opt);
La fonction renvoie true ou false en fonction de l’autorisation demandée et de l’auteur connecté (ou l’auteur demandé). Voici à quoi correspondent les différents arguments :
• $faire correspond à l’action demandée. Par exemple « modifier » ou « voir »,
• $type sert à donner généralement le type d’objet, par exemple « auteur » ou « article »,
• $id sert à donner l’identifiant de l’objet demandé, par exemple « 8 », 228 CHAPITRE 20. AUTORISATIONS
• $qui permet de demander une autorisation pour un auteur particulier. Non renseigné, ce sera l’auteur connecté. On peut donner comme argument à $qui un id_auteur. Cee variable sera remplie avec toutes les informa- tions, sous forme de tableau, concernant l’auteur désigné,
• $opt est un tableau d’option, généralement vide. Lorsqu’une autorisation nécessite de passer des arguments supplémentaires, ils sont mis dans ce tableau.
20.1.1 Exemple
1 if (autoriser(’modifier’,’article’,$id_article)) {
2 ^^I// ... actions
3 }
20.2 La balise #AUTORISER
Une balise #AUTORISER permet de demander des autorisations dans un squelee. La présence de cee balise, comme la présence de la balise #SESSION crée un cache de squelee par visiteur identifié et un seul cache pour les visiteurs non identifiés.
Cee balise prend les mêmes arguments que la fonction autoriser().
20.2.1 Exemple
1 [(#AUTORISER{modifier,article,#ID_ARTICLE})
2 ^^I... actions
3 ] 20.3. PROCESSUS DE LA FONCTION AUTORISER() 229 20.3 Processus de la fonction autoriser()
Les autorisations par défaut de SPIP sont écrites dans le fichier ecrire/inc/autoriser.php
Lorsque l’on demande à SPIP une autorisation autoriser($faire, $type), SPIP part à la recherche d’une fonction pour traiter l’autorisation demandée. Il recherche dans cet ordre une fonction nommée :
• autoriser_$type_$faire,
• autoriser_$type,
• autoriser_$faire,
• autoriser_defaut,
• puis la même chose avec le suffixe _dist.
20.3.1 Exemple
1 autoriser(’modifier’,’article’,$id_article);
Va retourner la première fonction trouvée et l’exécuter. C’est celle-ci :
1 function autoriser_article_modifier_dist($faire, $type, $id, $qui, $opt){
2 ...
3 }
La fonction reçoit les mêmes paramètres que la fonction autoriser(). Dedans, $qui est renseigné par l’auteur en cours s’il n’a pas été transmis en argument dans l’appel à autoriser().
20.4 Créer ou surarger des autorisations
Pour créer une autorisation, il suffit de créer les fonctions adéquates. 230 CHAPITRE 20. AUTORISATIONS
1 function autoriser_documentation_troller_dist($faire, $type, $id, $qui, $opt) {
2 ^^Ireturn false; // aucun troll permis ! non mais !
3 }
Déclarer cee fonction permet d’utiliser la fonction autoriser(’troller’,’documentation’) ou la balise #AUTORISER{troller, documentation}.
20.4.1 Nouvelles fonctions, mais pas n’importe où !
La fonction autoriser(), à son premier appel, charge un pipeline du même nom. Cet appel du pipeline « autoriser » (p. 170) permet de charger les fichiers d’au- torisations pour un dossier squelees ou un plugin.
20.4.2 Exemple
Dans un squelette : _ Dans le fichier config/mes_options.php on ajoute l’appel d’une fonction pour nos autorisations :
1
2 $GLOBALS[’spip_pipeline’][’autoriser’] .= ”|mes_autorisations”;
3
4 function mes_autorisations(){
5 ^^Iinclude_spip(’inc/mes_autorisations’);
6 }
7 ?>
Ainsi lorsque le pipeline autoriser est appelé, il charge le fichier inc/mes_autorisations.php. On peut donc créer ce dossier et le fichier, qui contient les fonctions d’autorisations souhaitées, dans son dossier squelettes/. Dans un plugin : _ Pour un plugin, presque de la même façon, il faut déclarer l’utilisation du pipeline dans le plugin.xml :
1
2 ^^I
3 ^^I
4 20.5. LES ACTIONS SÉCURISÉES 231
Et créer le fichier en question en ajoutant absolument, dans le fichier que le pi- peline appelle, la fonction prefixePlugin_autoriser().
1
2 if (!defined(”_ECRIRE_INC_VERSION”)) return;
3
4 // fonction pour le pipeline, n’a rien a effectuer
5 function prefixePlugin_autoriser(){}
6
7 // declarations d’autorisations
8 function autoriser_documentation_troller_dist($faire, $type, $id, $qui, $opt) {
9 ^^Ireturn false; // aucun troll permis ! non mais !
10 }
11 ?>
20.5 Les actions sécurisées
Les actions sécurisées sont un moyen d’être certain que l’action demandée pro- vient bien de l’auteur qui a cliqué ou validé un formulaire.
La fonction autoriser() n’est pas suffisante pour cela. Par exemple, elle peut vérifier que tel type d’auteur (administrateur, rédacteur) a le droit d’effectuer telle genre d’action. Mais elle ne peut pas vérifier que telle action a effectivement été demandée par tel individu. C’est en cela que les actions sécurisées interviennent. En fait, elles vont permere de créer des URL, pour les liens ou pour les formulaires, qui transmeent une clé particulière. Cee clé est générée à partir de plusieurs informations : un nombre aléatoire regénéré à chaque connexion d’un auteur et stocké dans les données de l’auteur, l’identifiant de l’auteur, le nom de l’action et ses arguments. Grâce à cee clé, lorsque l’auteur clique sur le lien où le formulaire, l’action appelée peut vérifier que c’est bien l’auteur actuellement connecté qui a demandé d’effectuer l’action (et pas un malicieux personnage à sa place !) 232 CHAPITRE 20. AUTORISATIONS 20.6 Fonctionnement des actions sécurisées
L’utilisation d’actions sécurisées se passe en deux temps. Il faut d’abord générer un lien avec la clé de sécurité, puis lorsque l’utilisateur clique sur l’action, qui va exécuter une fonction d’un fichier dans le répertoire action/, il faut vérifier la clé.
20.6.1 La fonction securiser_action()
Cee fonction securiser_action, dans le fichier ecrire/inc/securiser_action.php, crée ou vérifie une action. Lors d’une création, en fonction de l’argument $mode, elle créera une URL, un formulaire, ou retournera simplement un tableau avec les paramètres demandés et la clé générée. Lors d’une vérification, elle compare les éléments soumis par GET (URL) ou POST (formulaire) et tue le script avec un message d’erreur et exit si la clé ne correspond pas à l’auteur actuel.
20.6.2 Génerer une clé
Pour générer une clé, il faut appeler la fonction avec les paramètres corrects :
1 $securiser_action = charger_fonction(’securiser_action’,’inc’);
2 $securiser_action($action, $arg, $redirect, $mode);
Ces quatre paramètres sont les principaux utilisés :
• $action est le nom du fichier d’action et de l’action correspondante (action/nom.php et fonction associée action_nom_dist())
• $arg est un argument transmis, par exemple supprimer/article/3 qui servira entre autre à générer la clé de sécurité.
• $redirect est une URL sur laquelle se rendre une fois l’action réalisée.
• $mode indique ce qui doit être retourné :
– false : une URL – -1 : un tableau des paramètres – un contenu texte : un formulaire à soumere (le contenu est alors ajouté dans le formulaire) 20.7. FONCTIONS PRÉDÉFINIES D’ACTIONS SÉCURISÉES 233
20.6.3 Dans une action, vérifier et récupérer l’argument
Dans une fonction d’action (action_nom_dist()), on vérifie la sécurité en ap- pelant la fonction sans argument. Elle retourne l’argument (sinon affiche une erreur et tue le script) :
1 $securiser_action = charger_fonction(’securiser_action’,’inc’);
2 $arg = $securiser_action();
3 // a partir d’ici, nous savons que l’auteur est bien le bon !
20.7 Fonctions prédéfinies d’actions sécurisées
Les actions sécurisées sont rarement générées directement en appelant la fonc- tion securiser_action(), mais plus souvent en appelant une fonction qui elle, appelle la fonction de sécurisation. Le fichier ecrire/inc/actions.php contient une grande partie de ces fonctions.
20.7.1 generer_action_auteur()
Particulièrement, la fonction generer_action_auteur() appelle directement la fonction securiser_action en renvoyant une URL sécurisée par défaut.
20.7.2 redirige_action_auteur()
Cee fonction admet à la place du 3e argument de redirection, 2 paramètres : le nom d’un fichier exec, et les arguments à transmere. SPIP crée alors l’url de redirection automatiquement.
20.7.3 redirige_action_post()
Identique à la fonction précédente sauf qu’elle génère un formulaire POST par défaut. 234 CHAPITRE 20. AUTORISATIONS
20.7.4 Exemple
Générer un lien pour changer les préférences d’affichage dans l’interface privée :
1 $url = generer_action_auteur(’preferer’,”display:1”, $self);
Lancer une action sur l’édition d’une brève, puis rediriger sur la vue de la brève.
1 $href = redirige_action_auteur(’editer_breve’,$id_breve,’breves_voir’, ”id_breve=$id_breve”);
Poster un formulaire puis rediriger sur la page « admin_plugin ». $corps contient le contenu du formulaire pour activer un plugin.
1 echo redirige_action_post(’activer_plugins’,’activer’, ’admin_plugin’,’’, $corps);
20.8 URL d’action en squelette
Une balise #URL_ACTION_AUTEUR permet de générer des URL d’actions sécuri- sées depuis un squelee.
1 #URL_ACTION_AUTEUR{action,argument,redirection}
20.8.1 Exemple
Supprimer le commentaire de forum demandé si l’auteur en a le droit bien sûr (autoriser(’configurer’) est bien vague, mais c’est celle appliquée dans le privé dans ecrire/exec/forum_admin.php]) ! 20.8. URL D’ACTION EN SQUELETTE 235
1 [(#AUTORISER{configurer})
3 ] 236 CHAPITRE 20. AUTORISATIONS 237
Chapitre 21
Actions et traitements
Le répertoire ecrire/action/ a pour but de gérer les actions affectant les conte- nus de la base de données. Ces actions sont donc la plupart du temps sécurisées.
21.1 Contenu d’un fiier action
Un fichier d’action comporte au moins une fonction à son nom. Un fichier action/rire.php devra donc déclarer une fonction action_rire_dist().
1
2 if (!defined(”_ECRIRE_INC_VERSION”)) return;
3
4 function action_rire_dist(){
5
6 }
7 ?>
21.1.1 Déroulement de la fonction
En général, la fonction principale est découpée en 2 parties : vérifications des autorisations, puis exécution des traitements demandés. 238 CHAPITRE 21. ACTIONS ET TRAITEMENTS 21.2 Les vérifications
21.2.1 Le bon auteur
La plupart des actions de SPIP vérifient uniquement que l’auteur en cours est bien le même que celui qui a cliqué l’action. Cela se fait avec :
1 $securiser_action = charger_fonction(’securiser_action’, ’inc’);
2 $arg = $securiser_action();
La fonction de sécurité tue le script si l’auteur actuel n’est pas celui qui a demandé l’action, sinon elle renvoie l’argument demandé (ici dans $arg).
21.2.2 Le bon argument
Ensuite, généralement, la variable $arg reçue est vérifiée pour voir si elle est conforme à ce qu’on en aend. Elle prend souvent la forme de « id_objet », parfois « objet/id_objet » ou plus complexe comme ici des éléments de date :
1 if (!preg_match(”,^\W*(\d+)\W(\w*)$,”, $arg, $r)) {
2 ^^Ispip_log(”action_dater_dist $arg pas compris”);
3 ^^Ireturn;
4 }
21.2.3 Et l’autorisation
Certaines actions vérifient en plus que l’auteur a bien l’autorisation d’exécuter cee action (mais en général cee autorisation est déjà donnée en amont : le lien vers l’action n’apparaissant pas pour l’auteur n’en ayant pas les droits). Par exemple :
1 if (!autoriser(’modererforum’, ’article’, $id_article))
2 ^^Ireturn;
3 // qui pourrait etre aussi :
4 if (!autoriser(’modererforum’, ’article’, $id_article)) { 21.3. LES TRAITEMENTS 239
5 ^^Iinclude_spip(’inc/minipres’);
6 ^^Iminipres(’Moderation’,”Vous n’avez pas l’autorisation de régler la modération du forum de cet article”);
7 ^^Iexit;
8 }
21.3 Les traitements
Lorsque toutes les vérifications sont correctes, des traitements sont effectués. Souvent, ces traitements appellent des fonctions présentes dans le même fichier, ou dans une librairie du répertoire inc/. Parfois l’action est simplement effectuée dans la fonction principale.
21.3.1 Exemple du réglage de la modération d’un article
1 // Modifier le reglage des forums publics de l’article x
2 function action_regler_moderation_dist()
3 {
4 ^^Iinclude_spip(’inc/autoriser’);
5
6 ^^I$securiser_action = charger_fonction(’securiser_action’, ’inc’);
7 ^^I$arg = $securiser_action();
8
9 ^^Iif (!preg_match(”,^\W*(\d+)$,”, $arg, $r)) {
10 ^^I^^Ispip_log(”action_regler_moderation_dist $arg pas compris”);
11 ^^I^^Ireturn;
12 ^^I}
13
14 ^^I$id_article = $r[1];
15 ^^Iif (!autoriser(’modererforum’, ’article’, $id_article))
16 ^^I^^Ireturn;
17
18 ^^I// traitements
19 ^^I$statut = _request(’change_accepter_forum’);
20 ^^Isql_updateq(”spip_articles”, array(”accepter_forum” => $statut), ”id_article=”. $id_article);
21 ^^Iif ($statut == ’abo’) {
22 ^^I^^Iecrire_meta(’accepter_visiteurs’, ’oui’);
23 ^^I} 240 CHAPITRE 21. ACTIONS ET TRAITEMENTS
24 ^^Iinclude_spip(’inc/invalideur’);
25 ^^Isuivre_invalideur(”id=’id_forum/a$id_article’”);
26 }
Les traitements effectués modifient la table spip_articles dans la base de don- nées pour affecter un nouveau statut de gestion de forum. Lorsqu’un forum est demandé sur abonnement, c’est à dire qu’il faut être logé pour poster, il faut obli- gatoirement vérifier que le site accepte l’inscription de visiteurs, c’est ce que fait ecrire_meta(’accepter_visiteurs’, ’oui’);. Enfin, un appel à l’invalidation des fichiers du cache est effectué avec la fonction suivre_invalideur(). Tout le cache sera recréé (avant SPIP 2.0, cela n’invali- dait qu’une partie du cache).
21.4 Redirections automatiques
À la fin d’une action, après le retour de la fonction, SPIP redirige la page sur une URL de redirection envoyée dans la variable redirect. Les fonctions pour générer les liens vers les actions sécurisées, comme generer_action_auteur() ont un paramètre pour recevoir ce lien de redirection.
21.4.1 Forcer une redirection
Certaines actions peuvent cependant forcer une redirection différente, ou définir une redirection par défaut. Pour cela, il faut appeler la fonction redirige_par_entete() qui permet de rediriger le navigateur sur une page différente. Exemple : Rediriger simplement vers l’URL de redirection prévue :
1 if ($redirect = _request(’redirect’)) {
2 ^^Iinclude_spip(’inc/headers’);
3 ^^Iredirige_par_entete($redirect);
4 } 21.5. ACTIONS EDITER_OBJET 241 21.5 Actions editer_objet
Les actions d’édition ont une petite particularité. Appelées par les formulaires d’édition des objets SPIP (dans le répertoire prive/formulaires/) depuis le fi- chier ecrire/inc/editer.php, elles ne reçoivent pas d’action de redirection et doivent retourner, dans ce cas là un un couple « identifiant », « erreur ». Le traitement du formulaire (CVT) gérant lui-même la redirection par la suite.
Pour cee raison, les fichiers action/editer_xx.php où xx est le type d’objet (au singulier) peuvent retourner un tableau :
1 if ($redirect) {
2 ^^Iinclude_spip(’inc/headers’);
3 ^^Iredirige_par_entete($redirect);
4 } else {
5 ^^Ireturn array($id_auteur,’’);
6 } 242 CHAPITRE 21. ACTIONS ET TRAITEMENTS 243
Chapitre 22
Authentifications
Le répertoire auth contient les différents scripts pour gérer la connexion des uti- lisateurs. Couplé avec l’API disponible dans le fichier ecrire/inc/auth.php, l’en- semble permet de définir de nouveaux modes d’authentification et de création d’utilisateurs de site SPIP. Deux modes d’authentification sont fournis dans SPIP :
• SPIP pour une connexion tout à fait normale,
• LDAP pour une connexion des utilisateurs via cet annuaire.
22.1 Contenu d’un fiier auth
Les différentes authentifications sont appelées au moment du login dans le fichier prive/formulaires/login.php. La première qui valide une authentification permet de loger une personne en train de s’identifier. La liste des différentes authentifications est décrite par une variable globale : $GLOBALS[’liste_des_authentifications’]. Cependant, les processus d’authentifications sont relativement complexes faisant entrer de nombreuses sécurités. Aux fonctions de vérifications sont transmises le login et le mot de passe (crypté en sha256 couplé à un nombre aléatoire - ou en clair dans le pire des cas lorsqu’il n’est pas possible de poser de cookies). 244 CHAPITRE 22. AUTHENTIFICATIONS
22.1.1 Fonction principale d’identification
Un fichier auth/nom.php doit posséder une fonction auth_nom_dist(). Cee fonction retourne un tableau décrivant l’auteur si celui-ci est authentifié.
1 if (!defined(”_ECRIRE_INC_VERSION”)) return;
2 // Authentifie et si ok retourne le tableau de la ligne SQL de l’utilisateur
3 // Si risque de secu repere a l’installation retourne False
4 function auth_spip_dist ($login, $pass, $serveur=’’) {
5 ...
6 } 245
Chapitre 23
Compilateur
Cee partie explique quelques détails de la transformation d’un squelee par le compilateur.
23.1 La syntaxe des squelettes
SPIP possède une syntaxe pour écrire des squelees construite avec un vocabu- laire réduit, mais extrêmement riche et modulaire. Cee syntaxe, définie dans le fichier ecrire/public/phraser_html.php contient des éléments tel que :
• la boucle
1
2 ... avant
3
4 ... pour chaque element
5
6 ... apres
7
8 ... sinon
9
• le champ (balise)
1 [ avant (#BALISE{criteres}|filtres) apres ] 246 CHAPITRE 23. COMPILATEUR
• l’argument ({args}, |filtre ou |filtre{args} sur les balises)
• le critère ({critere=param} sur les boucles)
• l’inclusion
1
• l’idiome (chaîne de langue)
1 <:type:chaine_langue:>
• le polygloe (
1
23.2 L’analyse du squelette
Lorsque le phraseur (le parseur) de SPIP analyse un squelee, il traduit la syn- taxe en un vocabulaire connu et compris du compilateur. On peut donc dire que le phraseur traduit une langue particulière (la syntaxe SPIP) qu’on nomme « syn- taxe concrète » en une langue précise qu’on nomme « syntaxe abstraite ». Elle est définie par des objets PHP dans le fichier ecrire/puclic/interfaces.php De cee analyse de la page, le phraseur crée un tableau la décrivant, séquentiel- lement et récursivement, en utilisant le vocabulaire compris du compilateur (les objets Texte, Champ, Boucle, Critere, Idiome, Inclure, Polygloe). Pour bien comprendre, observons quel tableau est généré par des petits exemples de squelees.
23.2.1 Un texte
Squelette :
1 Texte simple
Tableau généré : (issu d’un print_r) 23.2. L’ANALYSE DU SQUELETTE 247
1 array (
2 0 =>
3 Texte::__set_state(array(
4 ’type’ => ’texte’,
5 ’texte’ => ’Texte simple
6 ’,
7 ’avant’ => NULL,
8 ’apres’ => ’’,
9 ’ligne’ => 1,
10 )),
11 )
Le tableau indique que la premier élément lu sur la page (clé 0) est un élément « Texte », débutant sur la ligne 1, et possédant le texte ”Texte simple”.
23.2.2 Une balise
Squelette :
1 [avant(#VAL)après]
On peut comprendre du tableau ci-dessous, que le premier élément lu de la page est un Champ (une balise), que son nom est « VAL », qu’il n’est pas dans une boucle (sinon id_boucle serait défini), que ce qui est dans la partie optionnelle avant la balise est un élément « Texte » dont le texte est « avant ». Tableau généré :
1 array (
2 0 =>
3 Champ::__set_state(array(
4 ’type’ => ’champ’,
5 ’nom_champ’ => ’VAL’,
6 ’nom_boucle’ => ’’,
7 ’avant’ =>
8 array (
9 0 =>
10 Texte::__set_state(array(
11 ’type’ => ’texte’, 248 CHAPITRE 23. COMPILATEUR
12 ’texte’ => ’avant’,
13 ’avant’ => NULL,
14 ’apres’ => ’’,
15 ’ligne’ => 1,
16 )),
17 ),
18 ’apres’ =>
19 array (
20 0 =>
21 Texte::__set_state(array(
22 ’type’ => ’texte’,
23 ’texte’ => ’après’,
24 ’avant’ => NULL,
25 ’apres’ => ’’,
26 ’ligne’ => 1,
27 )),
28 ),
29 ’etoile’ => ’’,
30 ’param’ =>
31 array (
32 ),
33 ’fonctions’ =>
34 array (
35 ),
36 ’id_boucle’ => NULL,
37 ’boucles’ => NULL,
38 ’type_requete’ => NULL,
39 ’code’ => NULL,
40 ’interdire_scripts’ => true,
41 ’descr’ =>
42 array (
43 ),
44 ’ligne’ => 1,
45 )),
46 1 =>
47 Texte::__set_state(array(
48 ’type’ => ’texte’,
49 ’texte’ => ’
50 ’,
51 ’avant’ => NULL,
52 ’apres’ => ’’, 23.2. L’ANALYSE DU SQUELETTE 249
53 ’ligne’ => 1,
54 )),
55 )
23.2.3 Une boucle
Prenons un dernier exemple d’une boucle avec une balise, plus compliqué car il induit une référence circulaire dans le tableau généré. Observons : Squelette :
1
2 #TITRE
3
Cee boucle sélectionne l’article 3 et devrait afficher le titre de l’article. Le ta- bleau de la page si on tente de l’afficher finit par générer une erreur de récursion. L’observation montre que le second élément lu dans la boucle est un Champ (balise) nommé ”TITRE”. Ce champ contient une référence vers la boucle dans laquelle il est (’boucles’=>array(...)). Cee boucle contenant la balise qui appartient à la boucle contenant la balise qui appartient à … Tableau généré partiel
1 array (
2 0 =>
3 Boucle::__set_state(array(
4 ’type’ => ’boucle’,
5 ’id_boucle’ => ’_a’,
6 ’id_parent’ => ’’,
7 ’avant’ =>
8 array (
9 ),
10 ’milieu’ =>
11 array (
12 0 =>
13 Texte::__set_state(array(
14 ’type’ => ’texte’,
15 ’texte’ => ’ 250 CHAPITRE 23. COMPILATEUR
16 ’,
17 ’avant’ => NULL,
18 ’apres’ => ’’,
19 ’ligne’ => 1,
20 )),
21 1 =>
22 Champ::__set_state(array(
23 ’type’ => ’champ’,
24 ’nom_champ’ => ’TITRE’,
25 ’nom_boucle’ => ’’,
26 ’avant’ => NULL,
27 ’apres’ => NULL,
28 ’etoile’ => ’’,
29 ’param’ =>
30 array (
31 ),
32 ’fonctions’ =>
33 array (
34 ),
35 ’id_boucle’ => ’_a’,
36 ’boucles’ =>
37 array (
38 ’_a’ =>
39 Boucle::__set_state(array(
40 ’type’ => ’boucle’,
41 ’id_boucle’ => ’_a’,
42 ’id_parent’ => ’’,
43 ’avant’ =>
44 array (
45 ),
46 ’milieu’ =>
47 array (
48 0 =>
49 Texte::__set_state(array(
50 ’type’ => ’texte’,
51 ’texte’ => ’
52 ’,
53 ’avant’ => NULL,
54 ’apres’ => ’’,
55 ’ligne’ => 1,
56 )), 23.3. PROCESSUS D’ASSEMBLAGE 251
57 1 =>
58 Champ::__set_state(array(
59 ’type’ => ’champ’,
60 ’nom_champ’ => ’TITRE’,
61 ’nom_boucle’ => ’’,
62 ’avant’ => NULL,
63 ’apres’ => NULL,
64 ’etoile’ => ’’,
65 ’param’ =>
66 array (
67 ),
68 ’fonctions’ =>
69 array (
70 ),
71 ’id_boucle’ => ’_a’,
72 ’boucles’ =>
73 array (
74 ’_a’ =>
75 Boucle::__set_state(array(
76 ...
23.2.4 Pourquoi de telles références ?
Tout simplement parce qu’elles servent ensuite dans le calcul des balises. Lors- qu’une balise est calculée, une partie de ce tableau lui est passée en paramètre (le fameux $p que l’on recroisera). Cee partie concerne simplement les informa- tions de la balise. Pour obtenir des informations de sa boucle englobante, il suffit, grâce à cee référence, d’appeler le paramètre $p->boucles[$p->id_boucle].
23.3 Processus d’assemblage
La production d’une page par le compilateur se réalise dans le fichier ecrire/public/assembler.php. Ce fichier appelle des fonctions pour analyser ce qui est demandé, récupérer le squelee adapté, le traduire en PHP, retourner le résultat de l’évaluation du code PHP. Le tout en gérant des caches.
SPIP utilise généralement la fonction recuperer_fond() pour récupérer le ré- 252 CHAPITRE 23. COMPILATEUR
sultat d’un squelee mais il appelle aussi directement la fonction assembler() depuis le fichier ecrire/public.php.
23.3.1 Cascade d’appels
La fonction recuperer_fond() appelle evaluer_fond() qui appelle inclure_page() qui appelle la fonction cacher() du fichier ecrire/public/cacher.php. C’est cee même fonction cacher() qu’appelle aussi assembler().
23.4 Déterminer le cae
Le fichier ecrire/public/cacher.php permet de gérer les fichiers du cache.
La fonction cacher() récupère le nom et la date d’une page en cache si elle existe, en fonction du contexte qui lui est donné. Si l’on transmet en plus une adresse de fichier, alors le fichier cache est créé. Ainsi, cee fonction peut-être appelée 2 fois :
• la première fois pour déterminer le nom du fichier de cache et pour indiquer si un cache valide existe pour la page demandée. • Une seconde fois lorsqu’il n’y a pas de cache valide. La page est alors cal- culée par la fonction parametrer(), puis la fonction cacher() est alors appelée pour stocker cee fois le résultat en cache.
1 // Cette fonction est utilisee deux fois
2 $cacher = charger_fonction(’cacher’, ’public’);
3 // Les quatre derniers parametres sont modifes par la fonction:
4 // emplacement, validite, et, s’il est valide, contenu & age
5 $res = $cacher($GLOBALS[’contexte’], $use_cache, $chemin_cache, $page, $lastmodified);
23.5 Paramètres déterminant le nom du squelette
Le fichier ecrire/public/parametrer.php permet de créer des paramètres qui se- ront nécessaires pour récupérer le nom et les informations du squelee à com- piler via styliser() puis demander son calcul via composer(). 23.6. DÉTERMINER LE FICHIER DE SQUELETTE 253
Ainsi la fonction parametrer() calcule la langue demandée ainsi que le numéro de la rubrique en cours si cela est possible. Ces paramètres permeent alors de trouver le nom et l’adresse du squelee cor- respondant à la page demandée. Cela est fait en appelant la fonction styliser() qui reçoit les arguments en question.
23.6 Déterminer le fiier de squelette
Le fichier ecrire/public/styliser.php détermine le nom et le type de squelee en fonction des arguments qui lui sont transmis.
1 $styliser = charger_fonction(’styliser’, ’public’);
2 list($skel,$mime_type, $gram, $sourcefile) =
3 ^^I$styliser($fond, $id_rubrique_fond, $GLOBALS[’spip_lang’], $connect);
Un 5e argument permet de demander un phraseur (une syntaxe concrète) et par conséquent une extension des fichiers de squelees différents. Par défaut, le phra- seur, donc l’extension utilisée, est html.
La fonction cherche un squelee nommé $fond.$ext dans le path de SPIP. S’il n’existe pas, elle renvoie une erreur, sinon elle tente de trouver un squelee plus spécifique dans le même répertoire que le squelee trouvé, en fonction des pa- ramètres d’id_rubrique et lang.
Styliser cherche alors des fichiers comme nom=8.html, nom-8.html, nom-8.en.html ou nom.en.html dans l’ordre :
• $fond=$id_rubrique
• $fond-$id_rubrique
• $fond-$id_rubrique_parent_recursivement
• puis ce qu’il a trouvé (ou non) complété de .$lang
La fonction retourne alors un tableau d’éléments de ce qu’elle a trouvé array($squelette, $ext, $ext, ”$squelette.$ext”) :
• 1er paramètre : le nom du squelee, 254 CHAPITRE 23. COMPILATEUR
• 2e : son extension • 3e : sa grammaire (le type de phraseur) • 4e : le nom complet.
Ces paramètres servent au composeur et sa fonction composer().
23.7 Une belle composition
Le fichier ecrire/public/composer.php a pour but de récupérer le squelee traduit en PHP et de l’exécuter avec le contexte demandé. Si le squelee a déjà été traduit en PHP, le résultat est récupéré d’un fichier cache et utilisé, sinon SPIP appelle sa fonction de compilation compiler() pour traduire la syntaxe concrète en syntaxe abstraite puis en code exécutable par PHP.
Le fichier composer.php charge aussi les fonctions nécessaires à l’exécution des fichiers PHP issus de la compilation des squelees.
23.8 La compilation
Le compilateur de SPIP, dans le fichier ecrire/public/compiler.php est appelé avec la fonction compiler() depuis la fonction parametrer(). La compilation commence par appeler le phraseur approprié en fonction de la grammaire demandée (la syntaxe concrète du squelee). C’est donc le phraseur phraser_html() qui est appelé, dans le fichier ecrire/public/phraser_html.php. Il transforme la syntaxe du squelee en un tableau ($boucles) de listes d’objets PHP formant la syntaxe concrète que va analyser la fonction de compilation. Pour chaque boucle trouvée, SPIP effectue un certain nombre de traitements en commençant par retrouver à quelles tables SQL elle correspond et quelles join- tures sont déclarées pour ces tables. Il calcule ensuite les critères appliqués sur les boucles (déclarés dans ecrire/public/criteres.php ou par des plugins), puis le contenu des boucles (dont les balises définies pour cer- taines dans ecrire/public/balises.php). Il calcule ensuite les éléments d’un sque- lee extérieur à une boucle. 23.8. LA COMPILATION 255
Il exécute enfin les fonctions de boucles qui sont déclarées dans le fichier ecrire/public/boucles.php. Le résultat de tout cela construit un code PHP exécutable avec une fonction PHP par boucle, et une fonction PHP générale pour le squelee. C’est ce code exécutable que retourne le compilateur. Ce code sera mis en cache puis exécuté par le composeur avec les paramètres de contexte transmis. Le ré- sultat est le code de la page demandé, qui sera mis en cache (par appel de la fonc- tion cacher() une seconde fois, dans le fichier assembler.php) puis qui sera envoyé au navigateur (ou si c’est une inclusion, ajouté à un fragment de page). Il peut encore contenir du PHP lorsque certaines informations doivent s’afficher en fonction du visiteur, comme les formulaires dynamiques. 256 CHAPITRE 23. COMPILATEUR 257
Chapitre 24
Cae
L’usage de différents caches est une partie intrinsèque de SPIP permeant de générer les différentes pages aux visiteurs plus rapidement, dans une optique de performance : on garde à portée de main les données qui sont souvent accédées, ou longues à calculer.
24.1 Cae des squelettes
Il existe différents caches dans SPIP, d’autres pouvant aussi être fournis par des plugins tel que « Mémoïsation », « Fastcache » ou encore « Cache Cool ». Un des caches essentiels est celui des squelees : le résultat de la compilation d’un squelee, donc le code PHP généré, est mis en cache dans le répertoire tmp/cache/skel. Ce cache a une durée de validité illimitée. Il sera recréé, pour un squelee donné, uniquement si :
• le squelee d’origine est modifié (en se basant sur la date du fichier sur le disque),
• le fichier mes_options.php ou mes_fonctions.php est modifié,
• le paramètre var_mode=recalcul est passé dans l’URL,
• le cache est manuellement vidé. 258 CHAPITRE 24. CACHE 24.2 Cae des pages
Un second niveau de cache est celui des pages demandées par les visiteurs du site. Leur résultat est sauvegardé, dans les répertoires tmp/cache/0 à f/ avec une durée de validité. Ces fichiers sont répartis dans plusieurs dossiers car dans un seul, leur nombre pourrait devenir trop important et avoir un impact sur les performances du système de fichiers du serveur. À noter que les fichiers de plus de 16ko sont automatiquement compressés (gz) si PHP dispose de la fonction gzcompress(). Ce cache est recréé lorsque :
• la durée de validité a expirée (définie dans les squelees par #CACHE ou en son absence par la constante _DUREE_CACHE_DEFAUT),
• le contenu éditorial de la base de donnée a été modifié. SPIP s’appuie sur la date de dernière modification pour le déterminer ($GLOBALS[’meta’][’derniere_modif’]) renseignée par la fonction suivre_invalideur() de ecrire/inc/invalideur.php,
• le paramètre var_mode=calcul est passé dans l’URL.
24.3 Cae SQL
SPIP met en cache certains éléments de la base de données pour éviter des appels intempestifs au serveur SQL et pour que l’affichage des pages publiques déjà en cache puisse fonctionner même si le serveur de base de donnée est indisponible. Deux caches sont ainsi créés.
24.3.1 Cae des métas
Le premier est un export complet de la table SQL spip_meta. Cee table stocke des paramètres de configuration ou de fonctionnement de SPIP. Ces informations sont à la fois déposées dans la globale $GLOBALS[’meta’] et, à l’exception des données sensibles servant à l’authentification, dans le fichier tmp/meta_cache.php. Ce fichier a une durée de validité définie par _META_CACHE_TIME. Il est réécrit lors de l’appel à ecrire_meta() ou effacer_meta(). La fonction lire_metas() elle recalcule $GLOBALS[’meta’] avec les informations de la base de données. 24.4. CACHE DES PLUGINS 259
24.3.2 Cae des descriptions SQL
Le second cache concerne la description des tables SQL des bases de données. Ces descriptions sont stockées dans les fichiers tmp/cache/sql_desc*.txt, avec un fichier par connecteur de base de données. Ce fichier est créé et utilisé par la fonc- tion base_trouver_table_dist() qui sert de base à diverses fonctions PHP en rapport avec les descriptions SQL comme table_objet(), id_table_objet(), objet_type().
Pour recréer ce fichier de cache, il faut explicitement appeler la fonction trouver_table() sans argument :
1 $trouver_table = charger_fonction(’trouver_table’,’base’);
2 $trouver_table();
24.4 Cae des plugins
Des fichiers de cache spécifiques aux plugins sont aussi créés dans tmp/ ou dans tmp/cache/.
24.4.1 plugin_xml.cae
Le résultat de l’analyse des différents fichiers plugin.xml est mis en cache dans le fichier tmp/plugin_xml_cache.gz. Ce fichier est recréé lors de l’écriture de la liste des plugins actifs via la fonction ecrire_plugin_actifs() qui appelle la fonction plugins_get_infos_dist() de ecrire/plugins/get_infos.php gérant la récupération des informations d’un plu- gin. Le fichier est aussi supprimé, comme de nombreux fichiers de cache lors des mises à jour de la structure de base de données.
24.4.2 Fiiers de argement des plugins
Les plugins déclarent des fichiers d’options, de fonctions et des actions à effec- tuer sur des appels de pipelines. L’ensemble des fichiers à charger est compilé dans 3 fichiers, recalculés lors d’un passage sur la page de gestion des plugins 260 CHAPITRE 24. CACHE ecrire/?exec=admin_plugin, d’un vidage du cache ou d’une mise à jour de la structure de la base de données :
• tmp/cache/charger_plugins_options.php contient la liste des fichiers d’options à charger,
• tmp/cache/charger_plugins_fonctions.php contient la liste des fichiers de fonctions,
• tmp/cache/charger_plugins_pipelines.php celle des fonctions à exé- cuter pour chaque pipeline.
24.5 Cae des emins
SPIP utilise différents dossiers pour rechercher les fichiers qui lui sont néces- saires. Lire à ce sujet La notion de chemin (p. 116). Lorsqu’il cherche un fi- chier via la fonction find_in_path — fonction qui sert de base à include_spip, charger_fonction, recuperer_fond, aux inclusions de squelees ou à la ba- lise #CHEMIN —, l’ensemble des chemins est parcouru jusqu’à trouver dedans le fichier recherché. L’ensemble de ces recherches crée de nombreux accès disques qu’il est bon de limiter.
SPIP met pour cela en cache, dans le fichier tmp/cache/chemin.txt, l’ensemble des correspondances entre un fichier demandé et son emplacement réel trouvé dans un des chemins. Ainsi, lorsqu’un fichier est demandé, SPIP cherche si le chemin est en cache. Si ce n’est pas encore le cas, il calcule son emplacement et enregistre le tableau de correspondance enrichi du nouveau fichier.
Ce fichier de cache est recréé par l’appel du paramètre var_mode=recalcul dans l’URL, ou par une vidange manuelle du cache.
24.6 Caes CSS et Javascript
L’extension « Compresseur » présente dans SPIP permet de compacter les diffé- rents éléments CSS et Javascript pour limiter le nombre d’appels sur le serveur et la taille des fichiers à obtenir. 24.7. CACHE DES TRAITEMENTS D’IMAGE 261
Cee compression est active par défaut dans l’espace privé, désactivable via la constante _INTERDIRE_COMPACTE_HEAD_ECRIRE.
1 define(’_INTERDIRE_COMPACTE_HEAD_ECRIRE’, true);
Cee compression peut s’activer sur l’espace public selon la configuration choi- sie. SPIP créera un fichier CSS compacté par type de média (screen, print…), et un fichier Javascript compacté pour tous les scripts externes connus dans le HEAD de la page HTML.
Ces fichiers sont mis en cache dans local/cache-js/ et local/cache-css/. Ces caches sont recalculés si le paramètre var_mode=recalcul est passé dans l’URL.
24.7 Cae des traitements d’image
SPIP dispose d’une librairie de filtres graphiques permeant par défaut de pou- voir redimensionner des images facilement. Ces fonctions sont définies dans ecrire/inc/filtres_images_mini.php. L’extension « Filtres Images et Couleurs » active par défaut offre de nombreux autres filtres, comme créer des images typo- graphiques ou utiliser masques, fusionner des images, extraire des couleurs… Afin d’éviter de recalculer plusieurs fois des traitements extrêmement gourmands, SPIP stocke les résultats des calculs effectués dans les répertoires local/cache- gd2 et local/cache-vignettes. Ces images en cache ne seront effacées que lorsque le cache des images est vidé depuis l’interface de SPIP ou lorsque le paramètre var_mode=images est trans- mis dans l’URL.
24.8 Actualisation du cae
Lors d’une utilisation normale de SPIP, avec des visites, des nouveaux articles publiés, le cache et l’actualisation des données est correctement géré. Par défaut (mais des plugins pourraient modifier ce comportement), dès que SPIP a connais- sance de modifications des contenus éditoriaux dans la base de donnée, il invalide tout le cache des pages. Une page demandée sera alors calculée de nouveau avant - ou après avec le plugin « Cache Cool » - d’être servie au visiteur. 262 CHAPITRE 24. CACHE
Il est souvent nécessaire de vider le cache manuellement lorsqu’on effectue des modifications directement sur les fichiers, particulièrement en meant à jour une feuille de style ou un script Javascript calculés par des squelees SPIP si les options de compressions sont actives. Se rappeler que :
• var_mode=calcul dans l’URL actualise le cache de la page
• var_mode=recalcul (pour des administrateurs) dans l’URL recompile le squelee puis actualise le cache de la page.
• passer sur la page de gestion des plugins ecrire/?exec=admin_plugin recalcule les fichiers de cache tmp/cache/charger_*.php des plugins, soit les listes de fichiers d’options, de fonctions et de pipelines.
• le navigateur a son propre cache, que ce soit pour les pages ou pour les éléments AJAX. Il faut aussi penser à le vider ; ce n’est pas forcément SPIP qui ne retourne pas les contenus aendus, mais peut être le navigateur qui retourne son cache.
24.9 Configurer le cae
Différents paramètres permeent de gérer plus finement le cache des pages de SPIP.
24.9.1 Durée du cae
Il est inutile de renseigner pour chaque squelee SPIP une durée de cache en utilisant la balise #CACHE. Cee balise est utile pour définir une durée de vali- dité différente de la valeur par défaut. Concrètement, une inclusion listant des actualités issues de syndications d’autres sites peut avoir un cache rafraichi plus souvent, peut être toutes les heures, que le reste du site. Dans la plupart des cas, il vaut mieux utiliser une durée de cache assez longue par défaut, puisque SPIP rend obsolète le cache si des modifications des contenus sont effectuées. 24.9. CONFIGURER LE CACHE 263
Le cache des pages est défini à une journée, qu’il est possible de changer avec la constante _DUREE_CACHE_DEFAUT, par exemple pour mere un mois de validité :
1 define(’_DUREE_CACHE_DEFAUT’, 24*3600*30);
24.9.2 Taille du cae
SPIP s’arrange pour que le cache ait une taille ne dépassant pas une certaine va- leur, qui est de 10Mo par défaut. La variable globale $GLOBALS[’quota_cache’] permet de changer cee valeur, en meant par exemple 100Mo :
1 $GLOBALS[’quota_cache’] = 100;
24.9.3 Validité du cae
Uniquement pour du développement ou pour débugguer, il peut être utile de modifier le fonctionnement ou l’usage du cache. Une constante _NO_CACHE (ou via un plugin « NoCache ») permet cela :
1 // ne jamais utiliser le cache
2 // ni meme creer les fichiers cache
3 define(’_NO_CACHE’, -1);
4
5 // ne pas utiliser le fichier en cache,
6 // mais stocker le resultat du calcul dans le fichier cache
7 define(’_NO_CACHE’, 1);
8
9 // toujours prendre les fichiers en cache s’ils existent
10 // s’ils n’existent pas, les calculer
11 define(’_NO_CACHE’, 0); 264 CHAPITRE 24. CACHE 265
Chapitre 25
Tâes périodiques (cron)
Le génie gère les tâches périodiques, ce qu’on appelle généralement un cron.
25.1 Fonctionnement du cron
Les tâches à exécuter sont appelées à chaque consultation de page par un visiteur sur le site. Le passage d’un visiteur n’exécute qu’une seule tâche par page appelée, s’il y en a effectivement à traiter.
Cependant, pour que les tâches soient appelées, la balise #SPIP_CRON doit être présente dans le squelee de la page. Cee balise renvoie une image vide mais lance le script de tâches à traiter. Un navigateur texte lance aussi les tâches pé- riodiques si la balise n’est pas présente.
Pour appeler le cron, il suffit d’exécuter la fonction cron(). Cee fonction peut prendre un argument indiquant le nombre de secondes qui doivent s’écouler avant qu’une autre tâche puisse être lancée, par défaut 60 secondes. Les appels par #SPIP_CRON sont mis à 2 secondes comme ceci :
1 cron(2); 266 CHAPITRE 25. TÂCHES PÉRIODIQUES (CRON) 25.2 Déclarer une tâe
Pour déclarer une tâche, il faut indiquer son nom et sa périodicité en secondes via le pipeline taches_generales_cron :
1 function monplugin_taches_generales_cron($taches){
2 ^^I$taches[’nom’] = 24*3600; // tous les jours
3 ^^Ireturn $taches;
4 }
Cee tâche sera appelée au moment venu. Les traitements sont placés dans un fichier du répertoire genie/, homonyme à la tâche (nom.php) et disposant d’une fonction genie_nom_dist(). La fonction reçoit en argument la date à laquelle s’est réalisé le dernier traitement de cee tâche. Elle doit retourner un nombre :
• nul, si la tâche n’a rien à faire
• positif, si la tâche a été traitée
• négatif, si la tâche a commencé, mais doit se poursuivre. Cela permet d’ef- fectuer des tâches par lots (pour éviter des timeout sur les exécutions des scripts PHP à cause de traitements trop longs). Dans ce cas là, le nombre négatif indiqué correspond au nombre de secondes d’intervalle pour la pro- chaine exécution.
25.2.1 Exemple
Cet exemple est simple, issu des tâches de « maintenance » de SPIP, dans le fichier genie/maintenance.php, puisqu’il exécute des fonctions et renvoie toujours 1, indiquant que l’action a été réalisée.
1 // Diverses taches de maintenance
2 function genie_maintenance_dist ($t) {
3 25.2. DÉCLARER UNE TÂCHE 267
4 ^^I// (re)mettre .htaccess avec deny from all
5 ^^I// dans les deux repertoires dits inaccessibles par http
6 ^^Iinclude_spip(’inc/acces’);
7 ^^Iverifier_htaccess(_DIR_ETC);
8 ^^Iverifier_htaccess(_DIR_TMP);
9
10 ^^I// Verifier qu’aucune table n’est crashee
11 ^^Iif (!_request(’reinstall’))
12 ^^I^^Iverifier_crash_tables();
13
14 ^^Ireturn 1;
15 } 268 CHAPITRE 25. TÂCHES PÉRIODIQUES (CRON) Sixième partie
Formulaires
269
271
SPIP dispose d’un mécanisme assez simple et puissant pour gérer les formulaires, dit CVT (Charger, Vérifier, Traiter) qui décompose un formulaire en 4 parties :
• une vue, qui est un squelee SPIP affichant le code HTML du formulaire, correspondant au fichier formulaires/{nom}.html,
• et 3 fonctions PHP pour charger les variables du formulaire, vérifier les éléments soumis et enfin traiter le formulaire, déclarées dans le fichier formulaires/{nom}.php. 272 273
Chapitre 26
Structure HTML
Les formulaires sont stockés dans le dossier formulaires/. Pour faciliter la réuti- lisation et la personnalisation graphique des formulaires, une syntaxe HTML est proposée.
26.1 Affier le formulaire
Un fichier formulaires/joli.html s’appelle dans un squelee par #FORMULAIRE_JOLI qui affiche alors le formulaire. Le HTML du formulaire suit une écriture standard pour tous les formulaires SPIP. Les champs du formulaire sont encadrés dans une liste d’éléments ul/li.
1
2
3
13
Pour le bon fonctionnement du formulaire, l’aribut action doit être renseigné par la variable #ENV{action} calculée automatiquement par SPIP. De même, la balise #ACTION_FORMULAIRE{#ENV{action}} doit être présente, elle calcule et ajoute des clés de sécurité qui seront vérifiées automatiquement à la réception du formulaire. elques remarques :
• Le formulaire est encadré d’une classe CSS formulaire_spip et d’une autre de son propre nom, formulaire_demo ici. Le nom peut être récupéré plus agréablement par le contexte #ENV{form} (ou #FORM directement), ce qui peut donner :
.
• Les balises
reçoivent des classes CSS editer_xx où xx est le nom du champ, et éventuelle- ment obligatoire pour indiquer (visuellement) que ce champ est obligatoire- ment à remplir.
• Les balises input ont une classe CSS nommée comme leur type (pour pal- lier à une déficience d’Internet Explorer en CSS qui ne comprenait pas input[type=text])
• Les boutons de soumission sont encadrés d’une classe CSS boutons
26.1.1 Utiliser AJAX facilement
Entourer la balise formulaire d’une classe CSS ajax indique à SPIP d’utiliser AJAX permeant de ne recharger que le formulaire et non toute la page.
1
2 #FORMULAIRE_JOLI
3
La fonction verifier() du formulaire peut retourner des erreurs si les champs soumis ne sont pas corrects ; nous le verrons plus tard. Pour afficher ces erreurs dans le HTML du formulaire, des classes CSS et un nommage sont proposés : En tête du formulaire, des erreurs (ou des messages de réussite) généraux :
1 [
(#ENV*{message_erreur})
]2 [
(#ENV*{message_ok})
]Pour chaque champ, un message et une classe CSS sur l’item de liste pour mar- quer visuellement l’erreur. On calcule le message du champ grâce à la variable #ENV{erreurs} qui recense toutes les erreurs des champs :
1 #SET{erreurs,#ENV**{erreurs}|table_valeur{xxx}}
2
3 ^^I[
]4
Ceci donne, au complet avec le formulaire précédent :
1
2 [
(#ENV*{message_erreur})
]3 [
(#ENV*{message_ok})
]4
5
17
Lorsqu’un formulaire possède de nombreux champs, on le divise généralement en différents blocs nommés fieldset en HTML. Il est proposé, pour de tels blocs, de les encadrer également dans des listes ul/li :
1 [...]
2
Le premier
posséde une classe CSS « fieldset ». En lieu et place des balises HTML
Pour afficher des listes d’éléments de type radio ou checkbox, on utilise un bloc
. Cee écriture permet d’avoir le bouton avant le label, d’avoir la liste radio en horizontal (via CSS).
1
2 ^^I
3 ^^I^^I
4 ^^I^^I
5 ^^I
6 ^^I
7 ^^I^^I
8 ^^I^^I
9 ^^I
10
Pour passer la liste en horizontal en CSS, il suffit d’indiquer que le bloc « choix » doit s’afficher inline :
1 .formulaire_spip .editer_syndication .choix {display:inline;}
26.5 Expliquer les saisies
Il est souvent nécessaire de donner une explication pour remplir correctement une saisie de formulaire. Pour cela, deux classes CSS à insérer dans une balise
ou peuvent être utilisées :
• explication (avec
) permet d’écrire une explication plus détaillée que le label du champ souhaité
• attention (avec ) met en exergue un descriptif proposé. À utiliser avec modération ! 278 CHAPITRE 26. STRUCTURE HTML
Ces deux descriptions complètent donc les autres options déjà citées erreur et obligatoire.
26.5.1 Exemple
1 #SET{erreurs,#ENV**{erreurs}|table_valeur{nom}}
2
3 ^^I
4 ^^I[
]5 ^^I
<:entree_nom_pseudo:>
6 ^^I
7
26.6 Affiage conditionnel
Les fonctions charger() ou traiter() peuvent indiquer dans leur réponse que le formulaire est éditable ou non. Cela se traduit par la réception d’un paramètre editable dans le squelee, qui peut servir à masquer ou non le formulaire (mais pas les messages d’erreur ou de réussite).
Il s’utilise comme ceci [(#ENV{editable}) ... contenu de